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About This Book 





Purpose 


This tutorial shows you how to use SilverStream eXtend Workbench to develop a Web Service. 
You will learn about: 


Audience 


Web Services and WSDL 

Registry Manager 

WSDL Editor 

Web Service Wizard 

Workbench projects 

Web applications packaged in J2EE WARs 


This tutorial is for developers who want an introduction to Workbench projects while learning 
about building a Web Service. 


Prerequisites 


Experience This tutorial assumes you are a Java programmer who wants to use Workbench 
to develop J2EE applications. It assumes you have the following background: 


Experience with the Java programming language 
Understanding of the general structure of XML 
Understanding of a graphical development environment 
General understanding of J2EE concepts such as servlets 


Understanding of how browsers and application servers interact in Web applications 


Software In addition to the Workbench software, you need: 


A J2EE application server for deploying the application 


If you already have this software, you can deploy the standards-based J2EE WAR to your 
application server using Workbench deployment commands when available or your server’s 
deployment tools. 
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If you don’t have the required software, you can download the trial version of the SilverStream 
eXtend Application Server from www.silverstream.com/appserv-download. 


Organization 


Here’s a summary of the lessons you’ll find in this book: 





Lesson Description 





1 Registries and WSDL for | Introduces the Registry Manager and the WSDL Editor 
Web Services 





2 Creating a Web Service Teaches how to use the Web Service Wizard to generate 
the files that wrap your Java class as a Web Service and 
how to deploy the Web Service as a WAR 





3 Creating a Client Teaches how to use the Web Service Wizard to generate 
Application for a Web files that a client application uses to call a remote Web 
Service Service 





4 Using Web Services in a Teaches how to build a Web application with a JSP page 
J2EE Web Application and JavaBean that call a Web Service; this client 
application uses the same code as was generated in the 
previous lesson 





5 Testing Techniques Demonstrates how a Web Service can return WSDL and 
how to use the TcpTunnel tool for viewing the SOAP 
messages sent between the client and the Web Service 
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1 Registries and WSDL for Web Services 





What you will learn 


This lesson describes the Workbench tools for working with online registries for Web Services. 
It also shows you how to use the WSDL Editor to create a file that describes a Web Service and 
can be published in a registry. 


You will learn about: 


e Registries for Web Services 
e Browsing registries in Workbench 
e Using the WSDL Editor 


What you will do 


Create a profile for a public registry 

Search for businesses 

Examine the services for a business 

Create a WSDL file for the Calculator Web Service 
Add a binding element 

Add a service element 


Change the Stylized view 


O SDR A ON a 


Generate a Java remote interface from WSDL 


How long will it take? About 20 minutes 


NOTE You don’t need to be running your J2EE application server for this lesson. 


Registries for Web Services 


When you want to make a Web Service publicly available or you want to find Web Services you 
can use, you use a registry. This lesson shows you how to identify a set of registries and how to 
search for offerings in those registries using the Registry Manager. 
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About registries 


A Web Service registry is a repository of information about Web Services and other services. It 
supports finding and publishing information about a business and its services. 


When providers create a Web Service, they can publish information about that service and their 
business in a registry so prospective consumers can discover the service and learn how to use it. 
When consumers want to find a Web Service, they can query the registry to find the services and 
businesses that fit their needs, and retrieve information about using those services. 


Registries store this business and Web Service information in a standard XML-based format 
such as Universal Description, Discovery, and Integration (UDDI) or Electronic Business 
eXtensible Markup Language (ebXML). Typically businesses hosting registries provide Web 
page or GUI interfaces to publish to and query the registry. Other tools can use standard APIs to 
present their own interfaces. 


Browsing registries in Workbench 


The Registry Manager is on the Registries tab of the Navigation Pane. It displays registered 
businesses in the top panel and services in the lower panel. You can get listings from one or 
more registries. 


To use the Registry Manager, you define profiles for the registries you want to access. (Profiles 
for several major registries are already defined for you.) Then you search for businesses or 
services by specifying a search string. Businesses or services that begin with that string are 
displayed in the browser. 


EXERCISE 1-1: Create a profile for a public registry 


In this exercise you'll look at the profile for the IBM Public Registry that is defined for you 
when Workbench is installed. 


1. Start Workbench. You can use the SilverStream eXtend Workbench shortcut on the 
Windows Start menu. 


2. Select Edit> Profiles from the menu. 





2 Browsing registries in Workbench 





3. 


In the Profiles dialog, select the Registries tab. 
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RZ m 
=~ Profiles x| 








Servers | (9 Databases i 


Registry Profiles are used for deploying Web Services. They specify the 
information necessary to deploy and inquire a given registry. 


Profile name: [IBM Public Registry =] _ New... 










Registry type: UDDI 
Registry version: 1.0 


Registry specific information: 


User name 


JF Include in Registry Search 





Inquiry URL http: Awwey-3 ibm.com/services/uddifinquiryapi 
Publish URL https: /Avwey-3 ibm.com/services/uddi/protect/publishapi 
















OK Cancel) Help 


4. Select IBM Public Registry in the Profile name dropdown list box. 
5. Click the Edit button to look at the profile. The profile has these values: 




















Option Value 

Profile name IBM Public Registry 

Registry type UDDI 

Inquiry URL http://www-3.ibm.com/services/uddi/inquiryapi 

Publish URL https://www-3.ibm.com/services/uddi/protect/publishapi 
User name Blank 

Credential 


Later if you create an account with IBM, you can fill in your 
account information to enable publishing to the IBM registry. 





Include in Registry 
Search 








Selected 


You can prevent a registry from being searched by clearing 
this check box; you don’t have to delete the profile 





6. Click OK to close the Edit a Registry Profile dialog. 


7. (Optional) Look at the profiles for the other registries that have been set up for you. 
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8. Click OK to close the Profiles dialog. 


EXERCISE 1-2: Search for businesses 
In this exercise you'll search for registered businesses whose names begin with X. 


1. In the Navigation Pane, select the Registries tab. 
The pane has two subpanes: Business and Service. 


2. Inthe Business text box, type the letter X and click the curved blue arrow beside the text 
box. 


TIP You can enter multiple search terms by separating them with a vertical bar (|). For 
example, to find businesses that begin with X and W, type X|W. 

The Registry Manager searches the registries you’ ve defined. This can take a while, so be 

patient; the search can take from 15 seconds to 4 or 5 minutes. You can stop the search and 

look at partial results by clicking the red Stop button. When the button is no longer red, the 

search is done. 


The results are displayed in the Business Pane. The first-level nodes in the expandable tree 
are registries, and the next level are business names. 


3. Scroll through the list or collapse the top-level nodes to see which registries returned 
results. You can make the pane wider or longer for better viewing. 


4. Expand the nodes for various businesses to see what information they provide. 
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5. Find XMethods—it’s in both registries—and expand its node to find out about its 
offerings. 


Business: 








Web services resource site 
EC) Services 

Methods Barnes and Noble Quote 
XMethods Currency Exchange Rates 
XMethods Delayed Stock Quotes [| 
Methods Pacific Bell SMS Service 

fF) age) XMaLpha Technologies, LLC. 

fe ge) XMS X Media Solutions 








B Directory | E] Project (R ) Registries 


Information about businesses 


The information in a registry is self-supplied. A business tells you what they want you to know 
and selects their own categories. 


The business section of a registry might include these types of information: 

















Information Icon | Description 

Business name = Business name used in this registry 
Description — A short phrase describing the business 
Categories Categories to which the business belongs 























Classification schemes come from at least three sources: 
NAICS codes for industry segments, UNSPSC for product 
and service classifications, and geographic information 
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Information Icon | Description 
Identifiers Information about the business, such as a DUNS number 
Services © A list of services offered by the business, such as Web 


Services callable via HTTP and other services such as sales 
and technical support contact information 


You can select a service name to display its details in the 
lower pane 

















TIP Try other searches using the Advanced Search options (click the binoculars button). For 
more information about Advanced Search, see Registry Manager in the Tools Guide. 


Examining the information for a service 


Web Services are just a subset of the types of services that a business might publish in a registry. 
A business might list services such as sales and support contact information, as well as 
programmed Web Services. 


EXERCISE 1-3: Examine the services for a business 


In this exercise yov’ ll find out about the information available for a service and how to get a 
WSDL file for a service if one is available. 


1. In the Business Pane of the Registry Manager, find the XMethods node and expand it to 
show its list of services. 
2. Click the XMethods Barnes and Noble Quote service. 


The Registry Manager retrieves information about the service and displays it in the 
Service Pane. 
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3. Expand the nodes in the Service Pane to see all of the information. You can resize the pane 
so you can see more of the information at once. 


Business: 






















aaj XMethods 
Web services resource site 
3-C) Services 


























XMethods Currency Exchange Rates 
XMethods Delayed Stock Quotes 
Methods Pacific Bell SMS Service X 


Service: 


gaj XMethods 
Returns book price from Barnes and Noble online store, given ISBN [lang: en] 
EQ bitawiservices xmethods net S0/soqn/Serviet/ipcrouter 
SOAP Binding for tmodel:XMethods Book Quote [lang: en] 
(=). tM XMethods Book Quote 
Interface for retrieval of book price given its ISBN number [lang: en] 
Overview URL: bttp Awww xmethods netmodels/BookQuote wsdl 
5- E Categories 
uddi-org:types: wsdlSpec 


B Directory] [j Project) {R} Registries 


4. To retrieve the WSDL file that describes this service, highlight the line with the tModel 
icon—it says XMethods Book Quote. 

















f=). tM XMethods Book Quote 
5. Click the Retrieve WSDL icon in the toolbar above the Service text box. 
R 
e/ 


The WSDL file for the Book Quote service opens in the WSDL Editor. For information 
about the WSDL Editor, see “Using the WSDL Editor” on page 9. 


For the Book Quote service you could also click the Overview URL link to display the 
WSDL in your browser. A browser that understands XML is required. 
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Information about services 


In the Service Pane, you can find out the technical details of a service offering. For a 
programmatically accessible service, the details include the URL for accessing the service and 
where to find information about the methods the service offers. 


A service entry in a registry might include these types of information: 





Information 


Icon 


Description 





Service name 


© 


The name of the service 





Business name 


The business offering the service 


















































Description — A short phrase describing the service 

Binding The URL for invoking the service 

tModel tM Data describing the service 
A UDDI registry stores the data as a tModel, which is a set of 
name/value pairs; the tModel node may be followed by a 
description 

Overview URL — The URL of a document describing how to use the tModel 
data 
For a Web Service, this is usually a WSDL document. 

Categories Categories for the service 


The categorization has two parts: a name (for example, uddi- 
org:types) and a value (for example, wsdlSpec). The value 
wsdlSpec specifies that a WSDL document is available for the 
service. Other types of services can use other classification 
schemes. 





TIP You can search for services without searching for businesses first. The basic search finds 
matches in service names, and Advanced Search (binoculars button) matches other 
services data. For more information, see Registry Manager in the Tools Guide. 
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Using the WSDL Editor 


The WSDL Editor is an XML editor with extra features for handling WSDL elements. Most of 
the time, you will use WSDL definitions for Web Services that you get from registries or that 
you generate with the Web Service Wizard. However, if you need to edit a WSDL file, the editor 
comes in handy. 


In Lesson 2, “Creating a Web Service”, you’ ll build a Calculator Web Service. The Web Service 
Wizard generates WSDL to describe the service, so it’s not necessary to create one from scratch. 
But for this lesson, that’s what you’ ll do. 


EXERCISE 1-4: Create a WSDL file for the Calculator Web Service 
In this exercise you'll create a new WSDL file that describes the Calculator Web Service. 
1. In Workbench, select File>New from the menu. 
2. Inthe New File dialog, select the Web Services tab, highlight WSDL, and click OK. 


Choose file type: 
(DEE Web Services | XML | 





©, New Web Service Existing Web Service 


Po) 
WS Create a new Web Service ne Use an existing Web Service 


W WSDL 


S Create a new WSDL file 





3. Inthe WSDL Wizard, specify this information: 























Option Value 

Definition Name CalculatorService 

Target Namespace urn:CalculatorImpl 

Documentation The four basic arithmetic operations 

Include WSDL template Selected 
If you don’t include the template, the wizard uses 
the definition name to name the file; but the other 
fields are ignored and the new file is empty 
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Click Finish. 


Workbench starts the WSDL Editor and displays the beginning of a WSDL Web Service 
definition in the Edit Pane. If you compared this opening text with the file generated by 
the Web Service Wizard, you would see minor differences—but don’t worry about it. 





CalculatorService.wsdl 





Ke 


<?xml version="1.0"?> 

<definitions name="CalculatorService™ 
targetNamespace="urn: CalculatorImpl" 
xnlns: tns="urn: CalculatorImpl" 
xnlns="http: //schemas.xmlsoap.org/wsdl/" 
xnlns:xsd="http: //winv.w3.org/1999/XMLSchema” 
xnlns: soap="http: //schemas.xmlsoap.org/wsdl/soap/"> 
<documentation> 

The four basic arithmetic operations 

</documentation> 


</definitions> 














O xm 


Select the following XML text and paste it into the editor on a blank line above the 
definitions end tag </definitions>. It’s rather long because it defines request and response 
messages for all four arithmetic operations. 


NOTE You could also use the editor’s tools to insert the message and portType elements. 
These tools are described in the next section. 


<types/> 

<message name="subtractRequest"> 

<part name="arg0" type="xsd:double"/> 
<part name="argl" type="xsd:double"/> 
</message> 
<message name="subtractResponse"> 
<part name="arg2" type="xsd:double"/> 
</message> 
<message name="divideRequest"> 
<part name="arg3" type="xsd:double"/> 
<part name="arg4" type="xsd:double"/> 
</message> 
<message name="divideResponse"> 
<part name="arg5" type="xsd:double"/> 
</message> 

<message name="DivideFault"> 

<part name="reason" type="xsd:string"/> 
<part name="x" type="xsd:double"/> 
<part name="y" type="xsd:double"/> 
</message> 

<message name="addRequest"> 

<part name="arg6" type="xsd:double"/> 
<part name="arg7" type="xsd:double"/> 
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</message> 
<message name="addResponse"> 
<part name="arg8" type="xsd:double"/> 
</message> 
<message name="multiplyRequest"> 
<part name="arg9" type="xsd:double"/> 
<part name="argl0" type="xsd:double"/> 
</message> 
<message name="multiplyResponse"> 
<part name="argl1" type="xsd:double"/> 
</message> 
<portType name="CalculatorImp1WS"> 
<operation name="subtract"> 
<input message="tns:subtractRequest"/> 
<output message="tns:subtractResponse"/> 
</operation> 
<operation name="divide"> 
<input message="tns:divideRequest"/> 
<output message="tns:divideResponse"/> 
<fault message="tns:DivideFault" name="fault1"/> 
</operation> 
<operation name="add"> 
<input message="tns:addRequest"/> 
<output message="tns:addResponse"/> 
</operation> 
<operation name="multiply"> 
<input message="tns:multiplyRequest"/> 
<output message="tns:multiplyResponse"/> 
</operation> 
</portType> 


Tools for inserting elements 


The editor has dialogs to assist you with inserting top-level WSDL elements. The WSDL in the 
editor is missing two important elements: binding and service. You'll use the editor tools to add 
them. 
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n 


EXERCISE 1-5: Add a binding element 


In this exercise yov’ll add a binding element, which specifies how messaging is handled. 


1. In the Edit Pane near the end of the file, click to set the insertion point on a blank line 
between the end tags for portType and definitions. 


</portType> 


[insertion point here] 


</definitions> 


2. Right-click to display the WSDL popup menu, select Insert WSDL Element, then select 
Binding from the second menu. 









</operation> 
</portType> 


Paste 
Select All 
E Go To Line... 
Text Tools 


Ctr 
Ctri+A 
Ctri+G 


» 














SDL Element 









sert WSI » Message... 
Validate Port Type... 








Binding A 


Service... 


3. In the Binding dialog, specify this information: 














Option Value 

Name CalculatorBinding 

Documentation SOAP Binding for Calculator service 
Port Type CalculatoriImpIWS 


TIP Use the dropdown list box to select a port type defined in 
the file 





Binding Protocol 








SOAP Binding 
Style: rpc 


Transport: http://schemas.xmlsoap.org/soap/http 
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The filled-in dialog looks like this: 
Enter information for the binding element. 


Name: 
CalculatorBinding 





Documentation: 
= Binding for Calculator service 





Port Type: 
FalculatorimawS hd | 


Binding Protocol 
@ SOAP Binding 
Style: 
pe X 
Transport: 


ftp: Jischemas.xmlsoap.org/soap/nttp 


© HTTP Binding 


yet + 


© User Defined 





4. Click OK. 


The XML inserted in the file includes binding information for each operation defined in 
the portType element. 


> 


[Bs 
EXERCISE 1-6: Add a service element 


In this exercise you'll add a service element, which specifies the URL a client application uses 
to invoke the deployed Web Service. 


1. In the Edit Pane near the end of the file, click to set the insertion point on a blank line 
between the end tags for binding and definitions. 
</binding> 
{insertion point here] 
</definitions> 
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2. Right-click to display the WSDL popup menu, select Insert WSDL Element, then select 
Service from the second menu. 
<soap:binding style="rpc" transport="http: //s 
</binding> 
| 
Jci 
</definit Gar 
Paste 
Select All 
B Qo To line... i 
“Text Tools 
Insert WSDL Element p Message... 
Binding... 
3. In the Service dialog, specify this information: 
Option Value 
Name CalculatorService 
Documentation URL for locally deployed Calculator Web Service 
4. Click Add to add a line for port information. 
5. Enter these values to describe the port: 
Option Value 
Name CalculatorPort 
Binding CalculatorBinding 
TIP Use the dropdown list box to select a binding defined in the 
file 
Address Type SOAP 
TIP Use the dropdown list box to select a type 
Location http://localhost/ProverbsCloud/Calculator/CalculatorImp1 
NOTE Location is the URL where the Web Service will be 
deployed. For this lesson, use the sample URL above; you 
don’t need a working URL yet. 
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The filled-in dialog looks like this: 


Enter information for the service element. 


Name 
(alculatorService 





Documentation: 
URL for locally deployed Calculator Web Service 





Parts: 


Name | Binding | Address Type Location Add 
CalculatorPort [CalculatorBinding SOAP ip: Mocalhost/Prove 
an a ine ns p Fey ; Delete | 








6. Click OK. 
This XML is inserted in the file: 


<service name="CalculatorService"> 
<documentation> 
URL for locally deployed Calculator Web Service 
</documentation> 
<port name="CalculatorPort" binding="CalculatorBinding"> 
<soap:address 
location="http://localhost/ProverbsCloud/Calculator/CalculatorImpl"/> 
</port> 
</service> 


The rest of this lesson shows you how to use some more features of the WSDL Editor. 


Stylized view 


The WSDL Editor has a second pane that displays the XML content of the WSDL document in 
a report format. You can customize the content and layout using XSL style sheets. You cannot 
edit in the Stylized view. 
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> 


B 
EXERCISE 1-7: Change the Stylized view 


In this exercise yov’ ll look at the views that are provided and find out where you can add your 
own custom view. 


1. With the WSDL file open in the Edit Pane, click the Stylized tab at the bottom of the pane. 


The format of the WSDL changes to the Details view, which presents the information in a 
more readable format. 








CalculatorService .wsdl* 


+ & 


CalculatorService WSD 


GoTo: Top service binding portType message types Imports References 





nameSpace prefix nameSpace URIs for: definitions 
targetNamespace: urn: Calculator Impl 
tns urn: Calculator Impl 
http: //schemas.xmlsoap.ong/wsdl/ 
xsd http://www. w3 .0org/1999/XML Schema 
soap http://schemas.xmlsoap.org/wsdl/soap/ 


The four basic arithmetic operations 


service: CalculatorService 
URL for locally deployed Calculator Web service 
port: name: CalculatorPort 
binding: CalculatorBinding 
soap:address: location: 
htip:/localhost/Proverbs Cloud/Calculator/CalculatorImpl 
GoTo: Top service binding portType message types Imports References 











binding: CalculatorBinding ira 


XML) FT Stylized 


2. Right-click in the editing area, then select Stylesheets on the popup menu and Summary 
on the second menu. 









Summary 


| Custom. Hp 
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Another formatted view appears. 


Right-click again in the editing area, then select Stylesheets on the popup menu and 
Custom on the second menu. 


In the Select Style Sheet dialog, you can choose the default style sheet: Details, Summary, 
or a custom style sheet. You can create your own XSL style sheets to present the 
information in different ways. 


ZZ Select Style Sheet Eg 
[Summary z] 





[ Set as default 





Click Cancel to close the dialog. 
Click the XML tab to return to the editable view. 


Save the file in a convenient directory, for example c:\WorkbenchProjects. Its name is 
CalculatorService.wsdl. Then close the file. 


WSDL Editor toolbar 


When you open the WSDL Editor, several buttons are added to the main toolbar. 


|W ® 5 


You can: 


Validate the XML against the WSDL DTD 


Publish the WSDL to a UDDI registry defined in the Workbench registry profiles; you 
need an account with the registry you select 


Generate a Java class that matches the methods defined in the WSDL file 


The next exercise will show you how to generate a Java class from WSDL. 
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< s 
EXERCISE 1-8: Generate a Java remote interface from WSDL 


In this exercise yov’ll create a remote interface and other Web Service classes from a WSDL 
specification. You could use the resulting Java files to create a new Web Service or client 
application. 


NOTE You need an open project for this exercise. You can use any project, since you won’ t be 
taking this any further than generating the code. Skip to Step 7 if you have an open 
project and want to generate the files there. 

1. In Workbench, close any open projects and select File>New Project from the menu. 

2. Inthe New Project Wizard, select JAR and then click OK. 












3% New Project Eg 
Choose the project type, or select Deploy-only if you 
you want to create a project for deployment of an 
existing archive file that you don't want to build. 


5 EAR WAR 
4 Enterp & Web Archive 


Enterprise Archive 


EJB. Ty CAR 
4 = Application Client Archive 


Enterprise JavaBean Archive 


p= RAR g JAR 
Resource Adapter Archive Java Archive! 


i | Deploy-only 
Non-buildable Archive 


OK Cancel Help | Cancel) Help 
3. Inthe Project Name field, type CalcWSDLTest. 


4. Click the ellipses beside the Project Location field and select a directory where you want 
to put Workbench projects, then type a new directory name (such as CaleWSDL). The 
Project Location field should end up with a value like this: 








C:\WorkbenchProjects\CalcwSDL 


The rest of the dialog is filled in automatically. 
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Enter the name and location (directory path) for 
the project and the archive file. (To use an 
existing archive as-is, create a deploy-only 
project instead.) 


Project Name: 


FalcwWSDLTest 


Project Location: 


FE:WoorkbenchProjects\CalcWSDL 8 


Archive Name (e.g. office war): 


FalcwSDLTest 


Archive Location (directory): 


E: WorkbenchProjects\Calc WSDL y 











Next> Gancel Help 


5. Click Next. If the project location directory doesn’t exist, confirm that you want to create 
it. 
On the last panel, check the project details then click Finish. 

7. Select File>Recent Files and open CalculatorService.wsdl again. 
In the WSDL toolbar, click the Generate Java Class button. 


X ® BiR SilverStream 





Workbench displays the project location panel of the Web Service Wizard. 


9. Fill in the panel as shown below. The only value you should have to specify is the calc 
package. 
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32 Web Service Wizard x] 


Specify the project, package, and base directory for the 
generated classes. 


(© Add to open project: [calcwSDLTest z] Create project... | 


@ No project -- just write files to the disk 











Base directory: F:WorkbenchProjects\CalcwSDLisre z] Browse... | 


Package: alc 
File directory: © C:'WVYorkbenchProjects\CalcVVSDLisrcicalc 

NOTE: The entire contents of this directory will be included in the archive. 
@ Add the files to the root of the archive. 


© Add the files to the archive with this prefix: | 


The files will be added to this location in the archive: 
calc 








package 





Mazer Next> Cancel Help 





Once you click Next, Workbench displays the class-generation and SOAP options panel 


of the Web Service Wizard. 


10. Examine the settings on this panel (you don’t need to change any of them). 


Specify the Web Service classes you would like to 
generate and any associated SOAP options. 











Generation Options 
[V Generate stubs 





[T Generate skeletons: @ Tie-based © Not tie-based 


[T Generate jBroker Web 1.x compatible classes 
Directory with local XSD files: 


[c:WorkbenchProjects aH | 


[V Map complex XML types to Java types 








Finish Cancel 





Help 
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These settings tell the wizard to generate stub classes for a Web Service client. It will put 
the generated files in the src\calc directory and add them to your project. You will learn 
more about these options in Lesson 2, “Creating a Web Service” and Lesson 3, “Creating a 
Client Application for a Web Service”. 


11. Click Finish. 


When the wizard finishes generating its output, you’ ll find the generated files in the 
src\cale directory under the project root directory. 


Typically you use a WSDL file as the starting point for generating stubs (including a remote 
interface and related classes) for a client application. However, if you generate skeletons, you’ Il 
have all you need to begin building a Web Service. The other code you need is a class that 
implements the remote interface with the business logic for the Web Service methods. 


About publishing 


Workbench also provides facilities for publishing information about your service. 


For most registries, you need to set up an account before you can publish. The registry profiles 
can store the URL for publishing and your ID and password. 


TIP To publish, you open a WSDL file describing your service in the Edit Pane. The toolbar 
for the WSDL Editor includes a Publish to Registry button. It displays a dialog that lets 
you specify the registry, the business name, and the service URL. For more information, 
see Registry Manager in the Tools Guide. 


WSDL Publishing Options x| 
Registry Profile: 





IBM Public 


Business Name: 


| Lookup... | 


WSDL Publish URL: 


ftp: enter server url}/CalculatorService wsdl 





OK Cancel) Help 
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Summary of what you’ve done 


Using Workbench tools You used these tools in Workbench: 
e Registry profiles (Edit> Profiles) 

e Registry Manager (Registries tab of Navigation Pane) 

e WSDL Editor 


Next lesson In the next lesson you will learn about the Web Service Wizard. You’ ll create a 
project and develop the code for the Calculator Web Service. 
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What you will learn 


In this lesson yov’ll learn how to set up a WAR project for a Web Service and run the Web 
Service Wizard to generate SOAP processing code for the service. All you need to provide is the 
Java class that implements the methods that users of your service will call—in this sample, it 
will be a Calculator with these simple methods: add, subtract, multiply, and divide. Then you’ ll 
deploy the Calculator Web Service and test it with test tools provided by the wizard. 


You will learn about: 


e Web Services using J2EE 

e Defining a WAR project for the service 
e Generating Web Service code 

e Getting ready to deploy 

e Updating the J2EE server’s classpath 

e Testing the Web Service 


What you will do 


Set up directories for your project 

Create a new project 

Add source code to the project 

Add the jBroker Web libraries to the project 
Build the project 

Run the Web Service Wizard 

Build the archive 


Examine the deployment descriptor 


(O: OOS 2 Se OT) a FO. Ns a 


Deploy the project 
Edit the test client code 


= 
2 


11. Test the Web Service with the generated client 


How long will it take? About 15 minutes 


NOTE You do need to run your J2EE application server to deploy the Web Service you create 
in this lesson. 





23 


2 Creating a Web Service 





Web Services using J2EE 


A Web Service is a component available on a remote server. Its interface is known, and you can 
call its methods via a standardized messaging protocol. 


In the J2EE world, you make a Web Service available by deploying it as a servlet in a Web 
archive (WAR) on a J2EE application server. A client application makes a remote method call 
using SOAP XML messages. The SOAP dispatcher on the remote server receives the messages 
and directs the method call to the Web Service servlet. The Web Service wraps the return value 
as a SOAP message and sends it back to the client. 


JAX-RPC and RMI 


SilverStream supports the J2EE model for developing Web Services, which is based on JAX- 

RPC (Java API for XML-based RPC) and RMI (Java Remote Method Invocation). The business 
method signatures are declared in a remote interface. The service uses a skeleton class and the 
client uses a stub to manage the communication between the service and the client application. 


Skeleton and tie The Web Service’s skeleton class implements the remote interface. The 
skeleton receives a SOAP request, translates arguments from XML to Java data types, and calls 
the business method. The Web Service can also include a tie class that extends the skeleton and 
delegates the method call to another class that implements the business method. 


Stub The client application uses a stub class that also implements the remote interface. When 
the client calls a method defined in the remote interface, the stub directs the call to the Web 
Service using an URL it has stored and transmits the method call as a SOAP message. 


You don’t need to worry about the implementation details of these classes; SilverStream 
provides tools that generate this code. 


Workbench and jBroker Web 


Workbench SilverStream eXtend Workbench provides a Web Service Wizard that 
generates the code for the communication between the Web Service and the client application. 
For the Web Service, all you need to provide is code for the business methods. For the client that 
calls a Web Service, you can generate the code from a WSDL file, which is an XML description 
of a Web Service. 
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jBroker Web jBroker Web is a JAX-RPC implementation that provides compilers and 
runtime support for Web Services on a J2EE application server. It’s included in Workbench, and 
the Web Service Wizard uses its compilers to generate Web Service code. As you’ll see, your 
deployed applications require access to jBroker Web and related API JARs. 


jBroker Web includes command-line tools that invoke its compilers directly, but you will not 
use them in this tutorial. For more information, see the jBroker Web help. 


The rest of this lesson teaches you how to build a Web Service, leading you through project 
setup, generating code with the wizard, and deploying and testing the result. 


Defining a WAR project for the service 


The Web Service Wizard in Workbench starts with a source object that implements or defines 
the business methods that you want to make available. There are several possible starting points 
in this process. You might begin with: 

e A Java class that implements your business methods 

e An interface that specifies signatures for your business methods 

e An EJB session bean 

e A WSDL service definition that specifies the operations of the Web Service 


The Calculator Web Service uses the CalculatorImpl class, which defines methods for basic 
arithmetic. It also uses the DivideFault class, which handles divide-by-zero exceptions. 


In this section you’ ll create a WAR project for the Calculator Web Service. First you'll do a little 
directory setup. Then you’ll start Workbench to create the project file and add 
CalculatorImpl.java to the project. 


| t 


EXERCISE 2-1: Set up directories for your project 
In this exercise you will create directories for your source files. 


1. Using your operating system tools, create a root directory for your project called 
CalculatorWS. You can put it at the root level of your disk drive or in a subdirectory of 
your choosing. The sample paths in the tutorial assume that you create CalculatorWS in 
the WorkbenchProjects directory. On Windows, it would look like this: 

c:\WorkbenchProjects\Calculatorws 


2. Inthe CalculatorWS directory, create a subdirectory called sre, and in the src directory, 
create a package subdirectory called calc. 
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3. Copy the files CalculatorImpl.java and DivideFault.java from the Workbench-install- 
dir\docs\tutorial\TutorialFiles\webservices directory to the Calculator WS\src\calc 
project directory. 


You now have a directory structure like this: 


WorkbenchProjects\CalculatorwWS\sre\calc 


sx 
EXERCISE 2-2: Create a new project 


In this exercise you will start Workbench and use the New Project Wizard to create a project for 
the Calculator Web Service. 


1. Start Workbench. You can use the SilverStream eXtend Workbench shortcut on the 
Windows Start menu. 
OR 
If Workbench is already running and a project is open, select File>Close Project from the 
menu. If prompted to close open files, click Yes. 

2. Select File>New Project from the menu. 


3. In the New Project Wizard, select WAR and then click OK. 





3% New Project x| 
Choose the project type, or select Deploy-only if you 
you want to create a project for deployment of an 
existing archive file that you don't want to build. 


A EAR £ WAR 
Enterprise Archive Web Archive 


EJB Ty CAR 
4 = Application Client Archive 


Enterprise JavaBean Archive 


Resource Adapter Archive Java Archive 


a Deploy-only 
Non-buildable Archive 











OK Cancel Help 


4. Inthe Project Name field, type Calculator. 

5. Click the ellipses beside the Project Location field and select the CalculatorWS 
directory you created in EXERCISE 2-1: “Set up directories for your project”. When you 
click OK, the rest of the dialog is filled in automatically. 
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6. Inthe Project J2EE Version field, specify J2EE 1.2 (WAR 2.2) so your application will 
run on any server that supports J2EE 1.2 or 1.3. 


Enter the name and location (directory path) for 
the project, the archive file, and the deployment 
descriptor and select the desired J2EE version. 
(To use an existing archive as-is, create a 
deploy-only project instead.) 


Project Name: 


Falculator 


Project Location: 


F:WorkbenchProjects\CalculatonwS EJ 





Archive Name (e.g. office war): 


Falculator 


Archive Location (directory): 


FWorkbenchProjects\Calculatorws p 


Deployment Descriptor Name: 


[veb xml 


Deployment Descriptor Location: 


E: WorkbenchProjects\CalculatorWS'WEB-INF B 
Project J2EE Version: J2EE 1.2 (WAR 2.2) z 











Nexte Cancel Help 


7. Click Next. 
When the wizard asks if it should create the WEB-INF directory, click Yes. 
The wizard summarizes the project information. 


NOTE If another project was open when you selected New Project, you might see a 
panel about adding the project to the current project. If this happens, do not check 
the Add this project option. Click Next to go to the summary panel. 


9. Click Finish. 


In the Navigation Pane, the Project tab displays the new project. You can use either a 
Source Layout view or an Archive Layout view. 
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me 
EXERCISE 2-3: Add source code to the project 


In this exercise you will add the src directory to the project and specify where it will be in the 


J2EE archive. 

1. In the Navigation Pane, click the Directory tab. 

2. Navigate to the WorkbenchProjects/CalculatorWS/sre directory. 

3. Right-click the sre directory and select Add to Project. 

4. Inthe Add to Project dialog, select Add the files to the archive at this location. In the 


5. 


me 
EXERCISE 2-4: Add the jBroker Web libraries to the project 


text box, type WEB-INF/classes. Leave Include subdirectories selected. 


ZZ Add to Project |x] 
File: [:WorkbenchProjects\Calculatorwstsre 


Add to project: [Calculator z] 


|V Include subdirectories 


© Add the files to the root of the archive. 


@ Add the files to the archive at this location: [KEB-INFiclasses 


Advanced => | 





OK Cancel Help 


Click OK. 


The Web Service uses classes in jbroker-web.jar and supporting JARs for SOAP message 
processing. In this exercise you will add these JARs to the archive for runtime access and to the 
project classpath for compile-time access. 


1. 
2. 
3. 


In Workbench, select Project>Project Settings from the menu. 
Select the Contents tab and click the Add Entry button. 
In the Select Contents dialog, navigate to the directory Workbench-install- 


directory/compilelib, then highlight the following files and click Open: 


e  jaxrpc-api.jar 
e jbroker-web.jar 


e  saaj-api.jar 
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e  xerces.jar 
The Add to Project dialog will prompt you for information about each file, one at a time. 


4. When you’re prompted about jaxrpc-api.jar, select Add the file to the archive at this 
location. In the text box, type WEB-INF/lib/jaxrpc-api.jar. Then click OK. 


5. When you’re prompted about jbroker-web.jar, select Add the file to the archive at this 
location. In the text box, type WEB-INF/lib/jbroker-web.jar. Then click OK. 


6. When you’re prompted about saaj-api.jar, select Add the file to the archive at this 
location. In the text box, type WEB-INF/lib/saaj-api.jar. Then click OK. 


7. When you’re prompted about xerces.jar, select Add the file to the archive at this 
location. In the text box, type WEB-INF/lib/xerces.jar. Then click OK. 


The WEB-INF/lib directory of the archive will now include these JARs. 


3 Project Settings x] 
Project: [Calculator z] 


General Contents | Classpath/Dependencies | 











Source location | Archive location 


VWEB-INF web.xml VWEB-INF web.xml 
|WEB-INFiclasses/ 
... WWEB-INF filbiaxrpo-api jar 
et |WWEB-INF fibjbroker-web jar 
... WWEB-INF fib/saaj-api jar 
... |WEB-INFdlibxerces jar 





"OK Cancel Help 


= 


8. Select the Classpath/Dependencies tab and click the Add Entry button. 
9. Inthe Add to Classpath dialog, find the directory Workbench-install-directory/compilelib 
again, then highlight the following files and click Open then OK. 
e  jaxrpc-api.jar 
e jbroker-web.jar 
e  saaj-api.jar 


e  xerces.jar 
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10. 


11. 


The Classpath/Dependencies tab should look something like this: 


Project: [Calculator bd | 


General | Contents Classpath/Dependencies 












Classpath entries: 





C:\Program Fil c ja 
Program Flos SiverStreamn\eXtendWorkbenchicomelels oroker- web jar 
“Program Files\SilverStreamiextendvVorkbenchicompilelib\saaj-api jar EJ 
“Program Files\SilverStreamieXtendyvorkbenchicompilelib\xerces jar 
P6SILVERSTREAM_XVVB_HOME% \compilelib'j2ee_api_1_2 jar 


In addition to directories and JAR files, you can add other project files (SPF files) to this 
project's classpath. Before this project is built, any SPF files listed here will automatically 
be built, and their generated archives will be used in the classpath. 


Add Entry... | Add Directory... | Edit... | Delete | 





J OK Cancel Help | ‘OK Gancel Help 


NOTE An archive of J2EE classes is already on the WAR’s classpath. Its path uses an 
environment variable whose value is the Workbench install directory. The 
variable was defined when you installed Workbench. 


Click OK to close the Project Settings dialog. 


The project now includes references to the required JARs. When you build the archive, 
these JARs will be included. The JARs are also on the classpath for building the archive. 


In the Navigation Pane, select the Project tab to see the project contents. Select Source 
layout, expand sre, and select the calc directory. It contains CalculatorImpl.java and 
DivideFault.java. Click the Workbench-install-directory/compilelib entry to see jbroker- 
web.jar and the other JARs in the lower pane. 


The expanded Source layout looks something like this: 





View using: Source layout z] 
& Calculator spt 
+} WEB-INF 
HH sre 
ES calc 

































C:\Program File: kbenchicompilelib 





La jaxrpc-api jar 
F) jbroker-web jar 
a saaj-api jar 

F) xerces jar 


B® Directory) g Project 
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EXERCISE 2-5: Build the project 
The Web Service Wizard uses compiled files, so you need to build the project before invoking it. 


e Select Project>Build from the menu. 


If you get errors, the problem is probably in the classpath. Make sure you successfully 
completed EXERCISE 2-4: “Add the jBroker Web libraries to the project’. 


Generating Web Service code 


To convert your source object into a Web Service, you run the Web Service Wizard. It generates 
code that enables the server to translate XML SOAP requests into method calls for your source 
object. 


TIP The Web Service Wizard requires that you have an open project. It puts the files it 
generates in that project. 


About the URL for the Web Service When you run the wizard, one of the pieces of 
information you will provide is the URL that clients use to access the service. The URL has 
several parts: 








Part Description Example 
Server URL for the server, including the port number http://localhost/Pr 
(if not the default port 80) and any server- overbsCloud/ 


Specue Oats http://www.mydo 


TIP For a SilverStream server, include the main.com:8080/ 
database to which you deployed the WAR 





Web application URL for the WAR Calculator/ 


TIP For a SilverStream server, this is a relative 
URL that you specify in the deployment 
plan 





Servlet mapping URL for the servlet; this is the URL pattern CalculatorImpl 
assigned in the Servlet Mapping section of the 
deployment descriptor 
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For example, when you deploy this Web Service to a local SilverStream server, the URL will be 
something like this: 


> 


B 


http://localhost :80/ProverbsCloud/Calculator/CalculatorImpl 


EXERCISE 2-6: Run the Web Service Wizard 


In this exercise you’ll generate classes that turn CalculatorImpl into a Web Service. 


1. 
2. 


With your project open in Workbench, select File>New from the menu. 


In the New File dialog, select the Web Services tab, select New Web Service, and click 
OK. 


3% New File x] 


Choose file type: 


(BEE Web Services | xm | 





E 2 New Web Service È Existing Web Service 
Use an existing Web Service 





Create a new Web Service 


@) WSDL 
5 Create anew WSDL file 


Workbench displays the project location panel of the Web Service Wizard. 
You can accept the defaults on this panel (as shown below) and click Next. 


3% Web Service Wizard Eg 


Specify the WAR or JAR project and base directory where 
the new Web Service classes should be added. 


( Add to open project: [Calculator z] Create project... | 


@ No project -- just write files to the disk 











Base directory: F:WorkbenchProjects\CalculatonwStsre z] Browse... | 
Package | 


File directory: © C:WVYorkbenchProjects\CalculatorvySisrc\ 
NOTE: The entire contents of this directory will be included in the archive. 
& Add the files to the root of the archive 


Add the files to the archive with this prefix 




















Help 
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4. When the class selection panel displays, highlight class cale.CalculatorImpl and click 


Next. 
3% Web Service Wizard Eg 












Select the class from which you would like to generate new 
Web Service classes. 





- Available Classes (2) 


Calculatorimpl 


class calc DivideFault 








Class location (directory or JAR) 


[c:WorkbenchProjects\CalculatorVStbuild\Calculator-classes WEB-INFiclasses 


ll S, sal 











@ AllClasses ( Remote Classes (© Non-Remote Classes ( EJB Classes 















2Back Next> Cancel Help 





NOTE By default, the wizard displays the compiled classes of your project. You can 
optionally list classes located elsewhere (such as in an archive) and filter the list 
to show only specific kinds of classes. 
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5. When the method selection panel displays, click Add All to use all four calculator 
methods. Then click Next. 











Select the methods you would like to expose in your new 


Web Service. 


r Selected class 


| calc .Calculatorimpl 


- Available Methods (0) —] 














- Selected Methods (4) - 
double add(double, double) 
double multiply(double, double) 

double subtract(double, double) 
double divide(double, double) 






























Add | Remove | Remove All | 


Gancel Help 


The class generation and SOAP options panel displays. 


6. Inthe Service address text box, specify the URL a client uses to access your service. 


The URL varies depending on your deployment server, as described in “About the URL 
for the Web Service” on page 31. For example, the URL for an application deployed to the 
ProverbsCloud database on a SilverStream server at www.mydomain.com might be: 


http: //www.mydomain.com/ProverbsCloud/Calculator/CalculatorImpl 
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3% Web Service Wizard x| 


Specify the Web Service classes you would like to generate 
and any associated SOAP options. 





~ Generation Options 
[M Generate stubs 
[V Generate skeletons: @ Tie-based ( Not tie-based 
[V Generate WSDL file 
[7 Generate jBroker Web 1.x compatible classes 


SOAP Options 


Target namespace: furn:calc.Calculatorimpl 
Service address: [http: Mocalhost/Calculator/Calculatorimpl 


Binding style: C Document style & literal encoding 
@ RPC style & SOAP encoding 











sh Cancel Help 





7. Click Finish. 


Wizard results 


After you run the wizard, several files are added to the calc directory of your project. Because 
the wizard adds them to a project directory, they are automatically part of the project. 


When you select all the generation options in the wizard, your project includes these files. The 


Java files are in the calc package directory. 





File Description 


Where used 





CalculatorImpIWS.java A remote interface that has 
declarations for the methods of 
your source object. It extends 
java.rmi.Remote. Each of the 
methods throws 
RemoteException. 


Web Service and 
client program 





CalculatorImpIWS_ServiceSkelet | A jBroker Web class that 

on.java processes SOAP messages on the 
server. You should never need to 
modify this class. 











Web Service 
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File 


Description 


Where used 





CalculatorImpIWS_ServiceTieSk 
eleton.java 


A jBroker Web class that extends 
the ServiceSkeleton with a 
setTarget() method for identifying 
the object that implements the 
Web Service methods. You should 
never need to modify this class. 


Web Service 





CalculatorImpIWSTie.java 


A delegator class that extends the 
TieSkeleton and sets the tie’s 
target to 
CalculatorImp!WSDelegate. 


Web Service 





CalculatorImp!WSDelegate.java 


A delegator class that implements 
the remote interface and calls the 
methods of the source object. It 
implements all the constructors of 
the source object. 


Web Service 





CalculatorImp!WSService.java 


A Service interface used by JAX- 
RPC clients to obtain the stub for 
the Web Service. You should 
never need to modify this class. 


Client program 





CalculatorImp!WSServiceImpl.ja 
va 


A Service implementation class 
that handles instantiation of the 
stub (CalculatorImp!WS_Stub). 
You should never need to modify 
this class. 


Client program 








CalculatorImp!WS_Stub.java 





A jBroker Web class that 
processes SOAP messages on the 
client. You should never need to 
modify this class. 





Client program 
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File Description Where used 





CalculatorImp!WSClient.java A standalone Java program for Testing only 
testing the Web Service. After you 
edit the code, use it to verify that 
the deployed Web Service works. 
The sample code is a model for 
code in a client program. 





CalculatorImp!WS.wsdl An XML description of the Web Registry 
Service for publishing in a 
registry. 


This file is saved in the src 
directory of the project, not in the 
calc package directory. 














The delegator classes CalculatorImp!WSDelegate and CalculatorImplWSTie work together to 
bind the source object to the SOAP-processing objects. You don't have to edit anything to 
produce a working Web Service. 


The binding—the URL for accessing the Web Service—is part of the code in the stub. You can 
override this URL in the client code that instantiates the stub. 


NOTE Ifyou run the wizard again, all these files get regenerated. Therefore if you need to 
change the code, it is better to define a class that extends the delegator class than to edit 
the generated code. 


If the business logic isn’t written If you had started this process with an interface 
instead of an implementation—if CalculatorImpl.java didn’t exist and you had only the file 
CalculatorImp!WS.java—you would need to write the business logic at this point. You could 
extend CalculatorlmplWSTie or CalculatorImpIWS_ServiceTieSkeleton and implement the 
business logic there, or write another class and set the target of Calculatorlmp]WSTie to point 
to it. 
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Getting ready to deploy 


Workbench can build and deploy archives for any J2EE application server. These instructions 
provide the information you need to deploy this tutorial application. For details and server- 
specific information, see Workbench Deployment Instructions. (You can also use your own 
server tools to deploy.) 


To deploy your Web Service, you will: 


1. Build the archive 
2. Look at servlet information that the wizard inserted in the deployment descriptor 


3. Create a server profile (already done if you’ ve deployed other applications to your server 
in Workbench) 


4. Create a server-specific file with runtime deployment information 
5. Specify Workbench deployment settings 


6. Deploy to your server 


About the deployment descriptor 


When you created the project, Workbench created an XML descriptor file appropriate to the 
type of archive you selected. For a WAR, the file is called web.xml. 


When you open web.xml for editing, the Deployment Descriptor Editor shows the XML 
elements in an expandable tree structure. You can also look at the raw XML. The editor uses the 
project’s compiled code to determine what to show, which is why you build the archive first. If 
it isn’t already built, Workbench offers to build it for you. 


EXERCISE 2-7: Build the archive 


In this exercise yov’ ll include the generated WSDL file at the root of the archive, then build the 
archive. Lesson 5, “Testing Techniques” explains the reason for including the WSDL file. 
1. Select Project>Add to Project>File from the menu. 


2. Inthe Add to Project dialog, find the sre directory under the project root, highlight 
CalculatorImpIWS.wsdl, and click Open. 
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3. Inthe second Add to Project dialog, select Add the file to the root of the archive and 


click OK. 
ZZ Add to Project Eg 
File: E- WorkbenchProjects\CalculatorwSisrc\CalculatorimpliWS wsdl 


Add to project: [Calculator z] 


Help 





4. In Workbench, select Project>Build and Archive from the menu to create a deployable 
archive for your project. 


i ; 
EXERCISE 2-8: Examine the deployment descriptor 
The wizard inserts information about the main servlet for the Web Service into the deployment 


descriptor. In this exercise you’ll take a look at that information so yov’ ll know where to find 
and change it if you ever need to. 


1. In the Navigation Pane, right-click the project file Calculator.spf and select Open 
Deployment Descriptor from the popup menu. 


NOTE You can also find web.xml in any Source or Archive view and double-click it to 
open it. 
If Workbench displays the Select Build Option dialog, accept the defaults and click OK. 


Workbench opens web.xml in the Edit Pane. The editor displays the Descriptor tab, 
showing the types of information the descriptor can include. 
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C:WWorkbenchProjectsCalculatorvVS WVEB-INF iweb xml 3 


a 8 Web Archive 


sy Context Parameters 
Ga 9 Servlets 
= ® Calculatorimpl 
A Initialization Parameters 
p] Role References 
=] Ss Servlet Mapping 
2 Calculatorimp! 
Mime Mapping 
e Welcome Files 
Ki Error Pages 
ál Tag Libraries 
ES] Resource References 
QÀ Security Constraints 
> Login Configuration 
ii Roles 
ies Environment 
iy EJB References 
































Descriptor 


2. Notice the CalculatorImpl item under the Servlets heading. It was added by the wizard. 
3. Right-click CalculatorImpl and select Properties from the popup menu. 
The property sheet displays the deployment properties for the servlet. 


3% Properties x] 








WAR 
Servlet name: 
Ẹalculatorimpl 
Type: @ Servlet C JSP 
Servlet class: 


alc. CalculatorimplwSTie | 
Load on startup: | 


Description: 








4. Notice that the value for Servlet class is calc.CalculatorImpIWSTie. This is the class 
that will run when the Web Service is invoked. 

5. Back in the Edit Pane, find and highlight the CalculatorImpl item in the Servlet 
Mapping section. 





40 Getting ready to deploy 


Tutorial: Building a Web Application 





The property sheet now displays the mapping properties. 


3% Properties x] 








Servlet name: 


Flalculatorimp! I 


URL pattern: 


Fealculatorimp! 


Notice that the value for URL pattern is CalculatorImpl, the same as the servlet’s name. 
You will use this value in the URL that accesses the Web Service. 

Close the deployment descriptor by clicking the button in the upper-right corner of the 
editor or selecting File>Close from the menu. 


Deploying the project 


If you’ ve done another Workbench tutorial, most of your deployment setup has already been 
done. This exercise gives you the main steps and provides the project-specific information 
you'll need to deploy this project. For detailed deployment instructions for all the supported 
servers, see Workbench Deployment Instructions. 


EXERCISE 2-9: Deploy the project 


1. 


If you haven’t created a profile for your server, select Edit>Profiles from the menu and 
create one now. 

C For information, see the server profile procedure in the deployment instructions. 
Use the following information to create the server-specific part of the deployment process. 


For most J2EE servers, the server-specific deployment information is in a separate file, 
usually in XML format. For some servers, you need to add it to your project so that it is 
built into the archive. 
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server in the deployment instructions. 


(2) For more information and exercises with detailed steps, select the section for your 





Server What to do 


What to specify 





Create a SilverStream 
deployment plan. In 
the Deployment Plan 
Editor, set values on 
the property sheet for 
the Web Archive 
item. 


SilverStream 


Enabled — True 
Deployed object name — Calculator 


Server Profile — Select the profile you 
defined from the dropdown list box 


Session timeout — 5 minutes, the default 


URLs — Calculator, the default 





Sun Reference Create a runtime 
Implementation | deployment 
descriptor called sun- 
j2ee-ri.xml with the 
content at right. Put it 
in a directory called 
META-INF and add 
the file to the project. 


<?xml version="1.0" 
encoding="Cp1252"?> 


<j2ee-ri-specific-information> 
<server-name></server-name> 
<rolemapping /> 
<web> 
<display- 
name>Calculator</display-name> 
<context - 
root>Calculator</context-root> 
</web> 
</j2ee-ri-specific-information> 





Jakarta Tomcat — 





BEA WebLogic | Create a WebLogic 
descriptor called 
weblogic.xml with 
the content at right. 
Add it to the project 
in the WEB-INF 
directory. 














<!DOCTYPE weblogic-web-app 
PUBLIC "-//BEA 

Systems, Inc.//DTD Web 
Application 6.0//EN" 
"http://www.bea.com/servers/wls6 
10/dtd/ 

weblogic-web-jar.dtd"> 


<weblogic-web-app> 
<description> 
Calculator Web Service 
</description> 
<weblogic-version> 
</weblogic-version> 
</weblogic-web-app> 
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Server 


What to do What to specify 





IBM WebSphere 





Oracle91AS 

















3. Specify deployment settings for your server by selecting Project>Deployment Settings 


from the menu. 


On the Server Profiles tab, select the server profile you defined above. If you have a 
secure server, specify values for User name and Password. 


On the Deployment Info tab, specify additional application-specific information, as 


follows. 


NOTE For these tutorials, do not check Enable Rapid Deployment. For information on 
how to use rapid deployment with your server, see Archive Deployment in the 


Tools Guide. 





Server 


Option and Value 





SilverStream 


SilverStream Deployment Plan — Select the plan you 
defined in Step 2 


Overwrite existing deployment — Selected 
Verbosity — 3 


Ignore compile errors — Not selected (if JSP pages don’t 
compile successfully during deployment, don’t deploy the 
archive) 





Sun Reference 
Implementation 





Jakarta Tomcat 





BEA WebLogic 








WebLogic Application Name — Calculator; used in the URL 
for accessing the Web application 
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Server Option and Value 





IBM WebSphere Node Name — Leave blank or specify a node you’ ve set up on 
your server 





Oracle9iAS Deployment Name — Calculator; used in the URL for 
accessing the Web application 


Target Path — Leave blank or specify a path you’ ve set up on 
your server 


Website Name — Accept the default value or specify a name 
you’ ve set up on your server 




















LQ) For more details, select the section for your server in the deployment instructions. 
4. Click Deploy in the Deployment Settings dialog. 
OR 
Click OK in Deployment Settings and select Project>Deploy Archive from the menu. 
Workbench displays progress messages, errors, and warnings on the Deploy tab of the 
Output Pane. 


TIP For most server types, full deployment will fail if your server is not running. For 
some servers you need to restart after deployment. For details, see the section for 
your server in the deployment instructions. 


Updating the J2EE server’s classpath 


Before running the Web Service, there is one more thing to do. You must make sure that the 
deployed WAR has runtime access to the following archives required by jBroker Web: 
e  jbroker-web.jar, which contains the jBroker Web API classes 


e jaxrpc-api.jar and saaj-api.jar, which contain the Java API classes for XML-based RPC 
and SOAP processing 


e  xerces.jar or another XML parser 
How you set up this access depends on the type of J2EE server you use: 


If you deployed to one of the following servers, you must add the required JARs to the server’s 
classpath. (Consult your server documentation to learn about adding to the classpath.) 


e BEA WebLogic 
e IBM WebSphere 





44 


Updating the J2EE server’s classpath 





Tutorial: Building a Web Application 





e Jakarta Tomcat 
e  Oracle9i 
If you deployed to the SilverStream eXtend Application Server, you don’t need to add those 


JARs to the server’s classpath (the fact that they are in the WEB-INF/lib directory in the WAR 
is sufficient for the SilverStream server). 


Testing the Web Service 


The Web Service Wizard generates a Java class for testing the Web Service. After you make a 
few modifications to the template code, you can run the program to see what happens. 


EXERCISE 2-10: Edit the test client code 

1. Inthe Navigation Pane, find CalculatorImpIWSClient.java and double-click it to open it 
in the editor. In Source Layout, it’s in the src/calc directory; in Archive Layout, it’s in 
WEB-INF’/classes/calc. 

2. Inthe process() method, replace the four commented System.out.printIn() statements 
with this code. Do not remove the call to getRemote(). 
This new code gets arguments from the command line (or uses default values) and calls 
the CalculatorImp! methods. 

double x, y; 


if (args.length == 2) 
{ 
x = new Double(args[0]) .doubleValue() ; 
y = new Double(args[1]) .doubleValue() ; 
} 
else 
{ 
x = i 
Ye = i 


System.out.println ("Add = ht remote.add(x, y)); 
System.out.println ("Divide 
System.out.println("Multiply 


System.out.println("Subtract = " 


remote.divide(x, y)); 


remote.multiply(x, y)); 
remote.subtract (x, y)); 


1 
++ + + 


3. Select Project>Compile from the menu to save and compile the file. 


4. Close the file. 
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mf 


EXERCISE 2-11: Test the Web Service with the generated client 


1. 


4. 


Select Project>Run Web Service Client Class from the menu. 


The selection list in the Web Service Wizard Client Runner window displays the test client 
class. If your project included other compiled classes with main() methods, they would be 
listed too. 


In the Arguments text box, type two numbers, which are the input for the Calculator’s 
arithmetic operations. For example, you might type: 





4.0 5.5 
Click Run. 
The output from the System.out.printIn() methods displays in the output box. 
Client class to run: 
[eale CalculatorimplyySClient id | 


[T Show command line 





Arguments: 
fa 055 

Running calc.CalculatorImplUSClient... 
KKEKKEKKEKEEKEEKEAAEE 











Add = 9.5 

Divide = 0.7272727272727273 
Multiply = 22.0 

Subtract = -1.5 
KKEKKEKAEKAEKTEAAEAEE 


Run Close Clear 


by 


Click Close when you are done. 


Congratulations. You’ve successfully deployed and tested a Web Service. 


Summary of what you’ve done 


Developing the application In this lesson you built and deployed a WAR for a Web 
Service that provides several methods for basic arithmetic. You edited the code of the generated 
client program and ran the client to test the Web Service. 


Using Workbench tools You used these tools in Workbench: 


New Project Wizard (File>New Project) 
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e Add to Project menu item (Project> Add to Project) 
e Project Settings dialog (Project>Project Settings) 
e Web Service Wizard (File>New, Web Services tab) 


e Deployment tools (Open Deployment Descriptor on project popup menu, Edit>Profiles, 
Project>Deployment Settings, Project>Deploy Archive) 


e Web Service Wizard Client Runner window (Project>Run Web Service Client Class) 


Next lesson Inthe next lesson you will learn about generating client code from a WSDL file 
that describes a Web Service. 
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What you will learn 
When working with Web Services, there are two basic roles: 


e The service provider who writes and deploys a service 
e The service consumer who writes a client application that calls the methods offered by the 
service 


In Lesson 2, “Creating a Web Service” you played the role of provider and deployed the 
Calculator Web Service. In this lesson you’ll be a service consumer and use the Web Service 
Wizard to generate code that calls the Calculator Web Service. 


This lesson uses WSDL generated in Lesson 2, “Creating a Web Service” as its starting point. 
Although much of the code you need was already generated in that lesson, this lesson will 
proceed as if you had no source code for the Web Service, only a description file in Web 
Services Description Language (WSDL) format. 


You will learn about: 


e Getting information about a Web Service 
e Setting up your project 
e Generating client code from WSDL 


What you will do 
Set up a project directory and get the WSDL file 


Create a new project 

Set up a classpath for building the project 
Generate client code from WSDL 

Edit the test client code 


OO oe Oe No 


Test the Web Service with the generated client 


How long will it take? About 15 minutes 


NOTE This lesson assumes you completed Lesson 2, “Creating a Web Service” and deployed 
the Calculator Web Service. When you test this project, the J2EE application server 
where the Calculator Web Service is deployed needs to be running. 
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Getting information about a Web Service 


Web Services Description Language (WSDL) is a standard way to exchange information about 

a deployed Web Service. A WSDL file is an XML document that specifies the methods, data 

types, and URL of the Web Service. It allows the service to be described in an abstract, reusable 

way. 

There are several scenarios for getting a WSDL file. You might: 

e Geta WSDL file directly from a vendor who is deploying a service you want to use—for 
example, from a Web page or via e-mail 

e Define a WSDL specification for a service jointly with business partners 

e Use the Registry Manager to download a WSDL file from a public registry 

Once you have a WSDL file for a Web Service, you can use Workbench’s Web Service Wizard 


to generate client code that invokes the service. The generated files include a remote interface, 
service classes, a stub, and a client program for testing. 


Calculator Web Service In this lesson imagine that you gota WSDL file for the Calculator 
Web Service from another developer or business. In reality, you generated it in Lesson 2, 
“Creating a Web Service”. 


Setting up your project 


The client program you will build is a simple Java program, not a J2EE application stored in an 
archive. In Workbench you have to choose an archive type, so you’ll choose a JAR project. 
When you run the application, you can use either the command line or the Client Runner 
window. You won’t need to build and deploy an archive—just compile the files. 


EXERCISE 3-1: Set up a project directory and get the WSDL file 


1. Using your operating system tools, create a root directory for your project called 
CalculatorClient. You can put it at the root level of your disk drive or in a subdirectory of 
your choosing. The sample paths in this tutorial assume you created CalculatorClient in 
the WorkbenchProjects directory. On Windows, it would look like this: 

c:\WorkbenchProjects\CalculatorClient 


2. Copy the file CalculatorImpIWS.wsdl to the CalculatorClient directory. You’ ll find this 
file in the src directory of the project for Lesson 2, “Creating a Web Service”—for 
example, c:\WorkbenchProjects\CalculatorWS\src. 
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NOTE You can also get this file from Workbench-install- 
directory\docs\tutorial\TutorialFiles\webservices. If you do, it is important to 
open the file and edit the URL in the soap:address element at the end of the file to 
specify the URL where the Calculator Web Service is deployed. 


= 
EXERCISE 3-2: Create a new project 


In this exercise you will start Workbench and use the New Project Wizard to create a project for 
a client application that uses the Calculator Web Service. 


1. Start Workbench. You can use the SilverStream eXtend Workbench shortcut on the 
Windows Start menu. 
OR 
If Workbench is already running and a project is open, select File>Close Project from the 
menu. If prompted to close open files, click Yes. 

2. Select File>New Project from the menu. 


3. In the New Project Wizard, select JAR and then click OK. 












3% New Project x] 
Choose the project type, or select Deploy-only if you 
you want to create a project for deployment of an 
existing archive file that you don't want to build. 


5 EAR WAR 
S Enterp & Web Archive 


Enterprise Archive 


EJB I CAR 
4 = Application Client Archive 


Enterprise JavaBean Archive 


B RAR g JAR 
Resource Adapter Archive Java Archive! 


r] Deploy-only 
Non-buildable Archive 


‘OK Cancel Help | Cancel! Help 


4. On the next panel, in the Project Name text box type CalculatorClient. 
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5. 


6. 


aÉ 


EXERCISE 3-3: Set up a classpath for building the project 


In this exercise you will use the Project Settings dialog to specify a compile-time classpath. For 
Web Services and Web Service clients, the classpath needs to include jbroker-web.jar and some 


supporting JARs. 

1. With your project open, choose Project>Project Settings from the menu. 

2. Select the Classpath/Dependencies tab. 

3. Click the Add Entry button. 

4. Inthe Add to Classpath dialog, navigate to the Workbench-install-directory/compilelib 


Click the ellipses beside the Project Location text box and select the CalculatorClient 
directory you created in EXERCISE 3-1: “Set up a project directory and get the WSDL 
file”. When you click OK, the rest of the panel is filled in automatically. 


Enter the name and location (directory path) for 
the project and the archive file. (To use an 
existing archive as-is, create a deploy-only 
project instead.) 












Project Name: 


FalculatorClient 


Project Location: 


z WVorkbenchProjects \CalculatorClient 


Archive Name (e.g. office.war): 


FalculatorClient 


Archive Location (directory): 


[WorkbenchProjects\CalculatorClient E 





_ Cancel 





Help 


Click Next, check the project specifications on the final panel, then click Finish. 
In the Navigation Pane, the Project tab displays the new project. 


directory. Highlight the following files and click Open then OK. 


e jaxrpc-api.jar 
e jbroker-web.jar 
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e  saaj-api.jar 
e  xerces.jar 
Now the Classpath/Dependencies tab should look something like this: 


3% Project Settings x| 
Project: [CalculatorClient z] 


General | Contents Classpath/Dependencies | 















Classpath entries: 






C:\Program Files StreameXtendVVorkbenchicompilelib\ 
“Program Files\SilverStream\extendvVorkbenchicompilelib bro! 
Program enero na ale voc barnes cleat -api jar | 
“Program Files\SilverStreamextendVVorkbenchicompilelib\xerces jar 

S6SILVERSTREAM_XVVB_HOME% \compilelib\j2ee_api_1_3.jar 







In addition to directories and JAR files, you can add other project files (SPF files) to this 
project's classpath. Before this project is built, any SPF files listed here will automatically be 
buit, and their generated archives will be used in the classpath. 


Add Entry... | Add Directory... | Edit... | Delete | 





TOK Cancel Help 


5. Click OK to close the Project Settings dialog. 


Generating client code from WSDL 


In Lesson 2, “Creating a Web Service”, you created a new Web Service starting with a Java 
class. Here you'll start with a WSDL file that represents an existing Web Service. 


ES 
EXERCISE 3-4: Generate client code from WSDL 
1. With your project open in Workbench, select File>New from the menu. 


2. Inthe New File dialog, click the Web Services tab, select Existing Web Service, and 
click OK. 
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3% New File x| 


Choose file type: 
J2EE Web Services | xm | 





yy New Web Service <}, Existing Web Service 
Create a new Web Service Use an existing Web Service 
A WSDL 
SY Create a new WSDL file 





Workbench displays the project location panel of the Web Service Wizard. 
3. Fill in the panel as shown below. The only value you should have to specify is the calc 


package. 












Specify the project, package, and base directory for the 
generated classes. 





( Add to open project: [CalculatorClient z] Create project... | 
@ No project -- just write files to the disk 





Base directory: FWorkbenchProjects\CalculatorClientisrc z] Browse... | 


Package: alc 





File directory: = C:WVYorkbenchProjects\CalculatorClientisrcicalc 
NOTE: The entire contents of this directory will be included in the archive. 


@ Add the files to the root of the archive. 


© Add the files to the archive with this prefix: | 


The files will be added to this location in the archive: 
calc 








package 








Help 


ai] 


Next> Cancel 
Once you click Next, Workbench displays the WSDL file selection panel of the Web 
Service Wizard. The file CalculatorImpl!WS.wsdl that you saved in the project root 
directory appears in the WSDL Files in Project list box. 


4. Highlight CalculatorImpIWS.wsdl so that it appears in the WSDL file or URL to use 
box. Then click Next. 





54 Generating client code from WSDL 





Tutorial: Building a Web Application 





Select the WSDL file or URL from which you would like 
to generate Web Services classes. 













> WSDL Files In Project 


C: WVorkbenchProjects\CalculatorClient\Calculatorimply 








r WSDL file or URL to use 


[C:WorkbenchProjects\CalculstorClient\CalculatorimpivS..wsdl Bi 


Cancel 

















Help 





The class generation and SOAP options panel displays. 


5. Examine the settings on this panel (you don’t need to change any of them). 


ZZ Web Service Wizard x| 


Specify the Web Service classes you would like to 
generate and any associated SOAP options. 





Generation Options 
[V Generate stubs 
[7 Generate skeletons: @ Tie-based © Nottie 





[7 Generate jBroker Web 1.x compatible classes 
Directory with local XSD files: 


[c:WorkbenchProjects\CalculatorClient 2i | 


M Map complex XML types to Java types 


= 


Finish” Gancel Help 





6. Click Finish. 
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Wizard results 


After you run the wizard, a new directory sre is added to your project. The cale package 
directory under it contains several new files. The Generate stubs option produces these files for 
use in a client application: 





File Description 





CalculatorImpIWS.java A remote interface that has declarations for the methods 
specified in the WSDL file. It extends java.rmi.Remote. 
Each of the methods throws RemoteException. 





CalculatorImp!WSService.ja | A Service interface used by JAX-RPC clients to obtain the 
va stub for the Web Service. You should never need to modify 
this class. 





CalculatorImp!WSServiceIm | A Service implementation class that handles instantiation 
pl.java of the stub (CalculatorImp!WSBinding_ Stub). You should 
never need to modify this class. 





CalculatorImp!WSBinding S | A jBroker Web class that processes SOAP messages on the 
tub.java client. You should never need to modify this class. 





CalculatorImp!WSClient.jav | A standalone Java program for accessing the Web Service. 








a After you edit the code, use it to call methods of the Web 
Service. 

DivideFault java An exception class thrown by the divide() method in the 
remote interface for this project. This file is specific to this 
project. 

DivideFaultMarshaler.java A marshaler that serializes and deserializes the 


DivideFault data type when it needs to be sent in a SOAP 
message. This file is specific to this project. 














Editing and testing the client application 


Code to instantiate the stub The generated client code obtains the stub by calling a 
method of the Service object (which is obtained via JNDI). The code looks like this: 


public CalculatorImplWS getRemote(String[] args) throws Exception 


{ 


InitialContext ctx = new InitialContext() ; 
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String lookup = "xmlrpc:soap:calc.CalculatoriImp1lWSService"; 
CalculatorImplWSService service = (CalculatorImplWSService) ctx.lookup (lookup); 
CalculatorImplWS remote = (CalculatorImp1WS) service.getCalculatorImp1WSPort () ; 


return remote; 


About the binding When you created the Calculator Web Service in Lesson 2, “Creating a 
Web Service”, you specified the binding—the URL for the Web Service—according to where 
you were going to deploy the Web Service. For the Calculator client, the wizard gets that 
binding from the WSDL and includes it in the generated stub. 


If the URL changes, you can override the binding in the stub like this: 


public CalculatorImpl1WS getRemote(String[] args) throws Exception 


{ 


InitialContext ctx = new InitialContext () ; 


String lookup = "xmlrpc:soap:calc.CalculatoriImp1lWSService"; 
CalculatorImplWSService service = (CalculatorImplWSService) ctx.lookup (lookup); 
CalculatorImplWS remote = (CalculatorImp1WS) service.getCalculatorImp1WSPort () ; 


((javax.xml.rpc.Stub) remote). setProperty("javax.xml.rpc.service.endpoint.address", 
"http: //www.myserver.com:80/Calculator/CalculatorImp1") ; 


return remote; 


For now, the original binding is what you want. Before you run the test client, all you need to do 
is edit the calls to the Web Service. You did these same steps when you tested the Web Service 
in Lesson 2, “Creating a Web Service”. 


EXERCISE 3-5: Edit the test client code 


In this exercise you'll use the same client test code as you used for testing the Web Service in 
Lesson 2, “Creating a Web Service”. 


1. Inthe Navigation Pane, find CalculatorImpIWSClient.java and double-click it to open it 
in the Edit Pane. In Source Layout, it’s in the src/calc directory. 


2. Inthe process() method, replace the four commented System.out.printIn() statements 
with the following code. Do not remove the call to getRemote(). 
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This new code gets arguments from the command line (or uses default values) and calls 
the four Calculator methods. 


double x, y; 
if (args.length == 2) 


{ 
x = new Double(args[0]) .doubleValue() ; 
y = new Double(args[1]) .doubleValue() ; 
} 
else 
{ 
x = i 
y= i 
} 


System.out.printIin ("Add = " + remote.add(x, y)); 

System. out.println ("Divide = " + remote.divide(x, y)); 

System.out.println("Multiply = " + remote.multiply(x, y)); 
( + 


System.out.println("Subtract = remote.subtract (x, y)); 
3. Save the file. 
4. Select Project>Build from the menu. 


The Build tab of the Output Pane should report a successful build. 












Buildfile: C:\WorkbenchProjects\CalculatorClient\build\build-CalculatorClient.xml a 
Building project "CalculatorClient" - June 13, 2002 12:54 PM 

Deleting directory C:\WorkbenchProjects\CalculatorClient\build\CalculatorClient-classes 

Could not find file C:\WorkbenchProjects\CalculatorClient\CalculatorClient.jar to delete. 

Created dir: C:\WorkbenchProjects\CalculatorClient\build\CalculatorClient-classes 

Compiling 7 source files to C:\WorkbenchProjects\CalculatorClient\build\CalculatorClient-classes 


BUILD SUCCESSFUL 


Total time: 3 seconds 


Ls] 
| x Build [Bi Deploy | [E> Find] yf Todo 











EXERCISE 3-6: Test the Web Service with the generated client 
1. Select Project>Run Web Service Client Class from the menu. 


The selection list in the Web Service Wizard Client Runner window displays the test client 
class. If your project included other compiled classes with main() methods, they would be 
listed too. 


2. Inthe Arguments text box, type two numbers—for example: 


4.0 5.5 
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3. Click Run. 
The output from the System.out.printIn() methods displays in the output box. 
Client class to run: 
fcac .CalculatorimphSClient E ] 


[> Show command line 





Arguments: 








AAAAAAAAAAAAAAAAAAATT 


Add = 9.5 
Divide = 0.7272727272727273 


Multiply = 22.0 
Subtract = -1.5 
KEKAKKEKKEKAEKAEAEEAE 





Rün Close Clear 
4. Click Close when you are done. 


Congratulations. You’ ve successfully invoked the publicly available Calculator Web Service. 


Summary of what you’ve done 


Developing the application In this lesson you used a Web Service description (WSDL) 
file to generate code that accesses a Web Service. 


Using Workbench tools You used these tools in Workbench: 


e New Project Wizard (File>New Project) 
e Project Settings dialog (Project>Project Settings) 
e Web Service Wizard (File>New, Web Services tab) 


e Web Service Wizard Client Runner window (Project>Run Web Service Client Class) 


Next lesson Inthe next lesson you will learn about building a Web application as a client for 
the Calculator Web Service. 
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Summary of what you’ve done 





Using Web Services in a J2ZEE Web 
Application 





What you will learn 


This lesson teaches you how to create a J2EE Web application that is a client of a Web Service. 
The Web application is a single JSP page. The JavaBean for the page has methods that 
instantiate a remote object and call the Calculator Web Service from Lesson 2, “Creating a Web 
Service”. 


You will learn about: 


e Defining a WAR project for the Web Service client application 
e Adding Web Service client code to the project 
e Creating a form that calls the Calculator Web Service 


e Deploying and testing the WAR 


What you will do 

Create a new project 

Add the jBroker Web libraries to the project 

Generate the client code for the Calculator Web Service 
Create a new JSP page 

Edit the JSP page 

Create a second JSP page to include in magicnumber.jsp 
Write a JavaBean to process the form 

Build the archive 


OS OoN OSR T Na 


Edit the deployment descriptor 


= 
> 


Deploy the project 
11. Test the Calculator Client application 


How long will it take? About 20 minutes 


NOTE You need to run your J2EE application server to deploy the WAR you create in this 
lesson. The Web Service you deployed in Lesson 2, “Creating a Web Service” must 
also be running. 
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Defining a WAR project for the Web Service client application 


In this section you’ll create a WAR project for a Web application whose pages call the 
Calculator Web Service. 


In the previous lesson you created the project directory, then defined the project in Workbench. 
This time you’ll let Workbench create the project root directory. 


E 
EXERCISE 4-1: Create a new project 


In this exercise you will start Workbench and use the New Project Wizard to create a project for 
a Web application. 


1. 


4. 


Start Workbench. You can use the SilverStream eXtend Workbench shortcut on the 
Windows Start menu. 

OR 

If Workbench is already running and a project is open, select File>Close Project from the 
menu. If prompted to close open files, click Yes. 

Select File>New Project from the menu. 


In the New Project Wizard, select WAR and then click OK. 





Z% New Project [x] 
Choose the project type, or select Deploy-only if you 
you want to create a project for deployment of an 
existing archive file that you don't want to build. 

















5 EAR rA WAR 
Enterprise Archive Web Archive 
EJB Ly CAR 
Enterprise JavaBean Archive Application Client Archive 
RAR E7 ; JAR 


Resource Adapter Archive Java Archive 


im | Deploy-only 
Non-buildable Archive 








OK Cancel Help 


In the Project Name field, type CalecWARClient. 
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5. Specify the full path for a project root directory called CaleWARClient in the Project 
Location text box. 
You can type something like c:\WorkbenchProjects\Calc WA RClient, or you can click 
the ellipses to select a parent directory in the Choose Directory dialog. Then you can type 
the new directory name in the Project Location text box after the selected directory. 
As you type, you see the rest of the dialog filled in automatically. 


6. Inthe Project J2EE Version field, specify J2EE 1.2 (WAR 2.2) so your application will 
run on any server that supports J2EE 1.2 or 1.3. 


Enter the name and location (directory path) for 
the project, the archive file, and the deployment 
descriptor and select the desired J2EE version. 
(To use an existing archive as-is, create a 
deploy-only project instead.) 


Project Name: 


FalcWARClient 


Project Location: 


FE: WorkbenchProjects\CalcWARClient | 





Archive Name (e.g. office war): 


FalcwARClient 


Archive Location (directory): 


FWorkbenchProjects\CalcWARClient E 


Deployment Descriptor Name: 


[veb xml 


Deployment Descriptor Location: 


E: WorkbenchProjects\CalcWARCIientiWEB-INF w 
Project J2EE Version: fr2ee 1.2 (WAR 2.2) z] 











Next> Cancel Help 


7. Click Next. 


8. When the wizard asks if it should create the project root and WEB-INF directories, click 
Yes. 


The wizard summarizes the project information. 
9. Click Finish. 
In the Navigation Pane, the Project tab displays the new project. 
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EXERCISE 4-2: Add the jBroker Web libraries to the project 


The Web Service client uses classes in jbroker-web.jar and supporting JARs for SOAP message 
processing. In this exercise you will add these JARs to the archive for runtime access and to the 
project classpath for compile-time access. 


1. 
2. 
3. 


With your project open, select Project>Project Settings from the menu. 

Select the Contents tab and click the Add Entry button. 

In the Select Contents dialog, navigate to the directory Workbench-install- 
directory/compilelib, then highlight the following files and click Open: 

e  jaxrpc-api.jar 

e jbroker-web.jar 

e  saaj-api.jar 

e  xerces.jar 

The Add to Project dialog will prompt you for information about each file, one at a time. 
When you’re prompted about jaxrpc-api.jar, select Add the file to the archive at this 
location. In the text box, type WEB-INF/lib/jaxrpc-api.jar. Then click OK. 

When you’re prompted about jbroker-web.jar, select Add the file to the archive at this 
location. In the text box, type WEB-INF/lib/jbroker-web.jar. Then click OK. 

When you’re prompted about saaj-api.jar, select Add the file to the archive at this 
location. In the text box, type WEB-INF/lib/saaj-api.jar. Then click OK. 
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7. When you’re prompted about xerces.jar, select Add the file to the archive at this 
location. In the text box, type WEB-INF/lib/xerces.jar. Then click OK. 


The WEB-INF/lib directory of the archive will now include these JARs. 











Project: [ealcwaRClient X | 
General Contents | Classpath/Dependencies | 











Source location | Archive location 
WEB-INFiweb xml [WEB-INF Aweb xml 


C:\Program Files \SilverStreamleXtendVVo... |WEB-INFilibjiaxrpc-api jar 
C:\Program Files \SilverStreameXtendvVo... |WEB-INF fib jbroker-web jar 
C:\Program Files\SilverStreamexXtendvVo... |WEB-INF jlib/saaj-api jar 
C:\Program Files\SilverStream\eXtendWo.... | WEB-INF fibixerces jar 





Add Directory... | Edit... | Delete | 
A OK Cancel Help | 


8. Select the Classpath/Dependencies tab and click the Add Entry button. 


9. Inthe Add to Classpath dialog, find the directory Workbench-install-directory/compilelib 
again, then highlight the following files and click Open then OK. 


e  jaxrpc-api.jar 
e jbroker-web.jar 





e — saaj-api.jar 


e  xerces.jar 
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The Classpath/Dependencies tab should look something like this: 


Z% Project Settings x] 
Project: [ealcwarClient z] 


General | Contents Classpath/Dependencies | 













Classpath entries: 





C:\Program Files’ StreameXtendyVYorkbenchicompilelibjaxrpc-ap 
“Program Files\SilverStream\extendvVorkbenchicompilelib\broker-web jar 
“Program Files\SilverStream\extendVVorkbenchicompilelib\saaj-api jar E] 
“Program Files\SilverStreamieXtendyvorkbenchicompilelib\xerces jar 
S6SILVERSTREAM_XVVB_HOME% \compilelib'j2ee_api_1_2 jar 


In addition to directories and JAR files, you can add other project files (SPF files) to this 
project's classpath. Before this project is built, any SPF files listed here will automatically 
be built, and their generated archives will be used in the classpath. 


Add Entry... | Add Directory... | Edit... | Delete | 





"OK Cancel Help | Cancel Help 


10. Click OK to close the Project Settings dialog. 


Adding Web Service client code to the project 


There are several classes that the Calculator WAR Client needs for accessing the Calculator Web 
Service: 

e  CalculatorImplWS.java 

e  CalculatorImplW SService.java 

e CalculatorImplWSServiceImpl.java 

e CalculatorImplWSBinding_Stub.java 

e  DivideFault.java 

e  DivideFaultMarshaler.java 

If you did Lesson 2, “Creating a Web Service” or Lesson 3, “Creating a Client Application for 
a Web Service”, the client files already exist in a calc package in those projects. Those lessons 
also explain what each file does. Although you could copy the files to this project or add them 


from their current location, instead yov’ll use the WSDL file from Lesson 2, “Creating a Web 
Service” to generate them again—it’s quick and easy to do. 
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EXERCISE 4-3: Generate the client code for the Calculator Web Service 


In this exercise you'll generate the client code from the WSDL file for the Web Service. This 
exercise is a synopsis of the same steps you did in Lesson 3, “Creating a Client Application for 
a Web Service”. For pictures and information about the results of the Web Service Wizard, see 
that lesson. 


1. 


Using your system tools, copy the file CalculatorImpIWS.wsdl to the CaleWARClient 
directory. You'll find this file in the src directory of the project for Lesson 2, “Creating a 
Web Service”—for example, c:\WorkbenchProjects\CalculatorWS\src. 

TIP If you didn’t do Lesson 2, “Creating a Web Service” and will use someone else’s 
deployed Calculator Web Service, you can get the file from the Workbench-install- 
directory\docs\tutorial\TutorialFiles\webservices directory. If you use this file, it 
is important to open it and edit the URL in the soap:address element at the end of 
the file to specify the URL where the Calculator Web Service is deployed. 

In Workbench, select File>New from the menu. 


In the New File dialog, click the Web Services tab, select Existing Web Service, and 
click OK. 


Workbench displays the project location panel of the Web Service Wizard. 
Specify the package calc and click Next. 


When the WSDL file selection panel displays, highlight CalculatorImpIWS.wsdl and 
click Next. 


The class generation and SOAP options panel displays. 


Examine the settings on this panel (you don’t need to change any of them), then click 
Finish. 


Your project should now contain the client code for calling the Calculator Web Service. 


Creating a form that calls the Calculator Web Service 


A JSP page with a form uses a companion JavaBean to manage the data in the form fields. 
Properties of the JavaBean store the entered values and make them available to methods in the 
bean for further processing. 
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The simple application in this lesson uses that approach. When the user submits the form with 
data, the associated JavaBean stores the submitted values. When the JSP page is redisplayed, it 
tests whether data was submitted. If so, it calls a method of the JavaBean that invokes the 
Calculator Web Service. When the application successfully calculates the “magic number”, a 
second JSP fragment is included in the original page to display the result. 


With the exercises in this section, you’ll create these files: 

















File Description 

magicnumber.jsp The main page of the application with an input form 

MagicNumberBean.java JavaBean that handles the data from magicnumber.jsp 

calcnumber.jsp JSP fragment that displays the calculated result via an 
include directive in magicnumber.jsp 











n 


A 
EXERCISE 4-4: Create a new JSP page 
In this exercise you will use the JSP Wizard to create a new page. 


1. In Workbench, select File> New from the menu. 


RZ m 
a New File x] 


Choose file type: 
J2EE } Web Services | xm | 


EJB Servlet 








" Create a new Enterprise JavaBean Create a new Servlet 
a) JSP {a Java file 
Create a new JavaServer Page Create a new Java class file 
Ka JavaBean fm) Tag handler 
Create anew JavaBean class file Create a new JSP tag handler 
abd Generic text file ee) SilverStream Deployment Plan 
Create a generic empty file Create a new SilverStream deployment plan 
Deployment Descriptor 





Create a new deployment descriptor 





i OK Cancel Help | GK Cancel Help 


2. Inthe New File dialog, select JSP and click OK. 
Workbench displays the JSP Wizard. 
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3. Fill out the first panel of the wizard with this information: 














Option Value 

JSP name magicnumber (don’t specify the jsp extension) 
Page title Magic Number 

Content type HTML (the default) 





Template 


Standard JSP template (the default) 





Other options 








Use session, Thread safe, Form-based page 








Now the first panel looks like this: 


Specify the JSP name and other options. 


JSP name: fragicnumber 
Page title: Magic Number 


Content type: HTL z] 


Template: [Etandara JSP template z] 


|V Use session 
|V Thread safe 
M Form-based page 


I Create error page 


[ Specify import values | 





4. Click Next. 


exte Cancel Help 


5. On the second panel, leave Add to open WAR project selected. 
6. Specify where to put the file in the project and the archive: 


e For Base directory, specify the full path for a new jsps directory—for example, 
c:\WorkbenchProjects\CalcWARClient\jsps. You can select another project directory 
path from the dropdown list and edit it. 


e For Package, leave it blank. In this project the JSP pages are at the root of the archive. 
e Leave Add the files to the root of the archive selected. 
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Specify the project, directory and package for the new JSP. 





( Add to open WAR project: [ealcwaRClient z] Create project... | 


© No project -- just write files to the disk. 








Base directory: FEWorkbenchProjectsiCalcwaRClentisps ë ë H Browse... | 
Package: DOO 
File directory:  C:WorkbenchProjects\CalcWARClientjsps\ 

NOTE: The entire contents of this directory will be included in the archive. 
@ Add the files to the root of the archive. 


© Add the files to the archive with this prefix: | 


The files will be added to this location in the archive: 














=Back Finish) Cancel Help 


7. Click Finish. 
8. When the JSP Wizard dialog reports that it is done creating the JSP page, click OK. 


The new file is open in the Edit Pane. In the Navigation Pane you can see 


magicnumber.jsp in the jsps directory of the Source layout and at the archive root of the 
Archive Layout. 


me 
EXERCISE 4-5: Edit the JSP page 


In this exercise you'll write the HTML and JSP code for a form that provides data for a 
calculation. 


NOTE You can copy the code for this exercise from the file CutAndPasteCode.txt in the 
Workbench-install-directory/docs/tutorial/TutorialFiles/webservices directory. 
OR 
If you don’t want to do these editing steps, you can use the correctly edited file 
magicnumber-sample.jsp in the same directory. Use your operating system tools to 
copy it to your project’s jsps directory and rename it magicnumber.jsp, replacing the 
file you just created with the JSP Wizard. 


1. With magicnumber.jsp open in the Edit Pane, add these lines after </head>: 


<jsp:useBean id="magicnumber" class="com.client .MagicNumberBean"/> 
<jsp:setProperty name="magicnumber" property="*"/> 
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2. Add these lines between <body> and </body>, replacing the existing text: 


<hl>Your Magic Number</h1> 
<p>Your magic number changes every day.</p> 


<form method="post"> 
<table> 
<tr> 
<td>Your age</td> 
<td> 
<input type="text" name="age" value="<%= magicnumber.getAge() %>" 


</td> 
</tr> 
<tr> 
<td>Day of month you were born</td> 
<td> 
<input type="text" name="birthday" value="<%= 
magicnumber.getBirthday() %>" > 
</td> 
</tr> 
<tr> 
<td>Hour you went to bed last night</td><td> 
<input type="text" name="bedtime" value="<%= 
magicnumber.getBedtime() %>" > 
</td> 
</tr> 
<tr 
<td span="2"> 
<input type="submit" name="Submit" value="Submit"> 
</td> 
</tr> 
</table> 
</form> 


if (request.getParameter("age") != null ) 
{ 


magicnumber.calcNumber () ; 


<%@ include file="calcnumber.jsp" %> 


3. Save and close the file. 
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EXERCISE 4-6: Create a second JSP page to include in magicnumber.jsp 


In this exercise you'll create a JSP fragment that is included in magicnumber.jsp when there is 
a calculated result to display. 


NOTE You can copy the code for this exercise from the file CutAndPasteCode.txt in the 
Workbench-install-directory/docs/tutorial/TutorialFiles/webservices directory. 
OR 
If you don’t want to do these editing steps, you can use the correctly edited file 
calcnumber-sample.jsp in the same directory. Use your operating system tools to 
copy it to the project’s jsps directory and rename it calenumber.jsp. 

1. In Workbench, select File>New from the menu. 

2. Inthe New File dialog, select JSP and click OK. 

Workbench displays the JSP Wizard. 


3. For JSP name, specify calenumber. The rest of the values don’t matter since you'll be 
replacing all the generated code. 


4. Click Next. 
5. On the second panel, leave Add to open WAR project selected. 
6. Specify where to put the file in the project and the archive: 


e For Base directory, specify the full path for the jsps directory—for example, 
c:\WorkbenchProjects\CalcWARClient\jsps. You can use the dropdown list box or the 
Browse button to select it. 


e For Package, leave it blank. In this project the JSP pages are at the root of the archive. 
e Leave Add the files to the root of the archive selected. 

7. Click Finish. 

8. When the JSP Wizard dialog reports that it is done creating the JSP page, click OK. 


The file is open in the Edit Pane. In the Navigation Pane you can see that calcnumber.jsp 
has been added to the jsps directory in the Source layout and the archive root in the 
Archive layout. 

9. Edit the file, replacing all the contents with this code: 


<h2>Drumroll...</h2> 


<table> 

<tr> 

<td>Your number is:</td> 

<td><%= magicnumber.getMagicNumber() %></td> 
</tr> 
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<tr> 

<td span="2">Did you expect a winning lottery number?</td> 

</tr> 

</table> 
As you can see, the code is not a complete HTML page. It will be included in the other 
JSP page. 


10. Save and close the file. 


EXERCISE 4-7: Write a JavaBean to process the form 


In this exercise you'll create a new Java source file by using the Java Class Wizard and then 
copy in the code for the JavaBean. (An alternative would be to use the JavaBean Wizard 
provided by Workbench. It is most useful when you’re creating your own JavaBeans from 
scratch.) 


NOTE You can copy the code for this exercise from the file CutAndPasteCode.txt in the 
Workbench-install-directory/docs/tutorial/TutorialFiles/webservices directory. 
OR 
If you don’t want to do these editing steps, you can use the correctly edited file 


MagicNumberBean-sample.java in the same directory. Use your operating system 
tools to create a directory called com\client under the src directory of your project, copy 


the file there, and rename it MagicNumberBean. java. 


1. In Workbench, select File>New from the menu. 
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RZ m 
a New File x] 


Choose file type: 
J2EE | Web Services| XML | 





= Es 


. Create a new Enterprise JavaBean 


Ky SSP 


Create a new JavaServer Page 


Ka JavaBean 


Create a new JavaBean class file 


abd Generic text file 


Create a generic empty file 





Deployment Descriptor 





[V Use wizard 


Create a new deployment descriptor 


Servlet 


Create a new Servlet 


{uh Java file 
Create a new Java class file 


{a} Tag handler 
Create a new JSP tag handler 








{ea} SilverStream Deployment Plan 


Create a new SilverStream deployment plan 


OK Cancel” Help 





2. Inthe New File dialog, select Java file and click OK. 
3. Inthe Java Class Wizard, specify these values: 











Option Value 
Class name MagicNumberBean (don’t specify the java extension) 
Base class Leave blank 





Create class or interface 


Class (the default) 





Template 


Standard Java class template (the default) 





Other options 








Public scope, Create default constructor, Serializable 
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Specify the class name and other options. 


Class name: MagichlumberBean 
Base class: | 


Create class or interface? 


@ Class 
C Interface 
Template: Standard Java class template z] 


[V Public scope. 

IV Create default constructor. 
I Create main() method. 

|) Serializable. 





Click Next. 

When the wizard prompts for interfaces to add, click Next to skip to the next panel. 
When the wizard prompts for additional imports, click Next to skip to the next panel. 
On the next panel, leave Add to open project selected. 


ON Oe ts 


Specify where to put the file in the project and the archive: 


e For Base directory, specify the full path for the sre directory—for example, 
c:\WorkbenchProjects\CalcWARClient\src. You will find this path on the dropdown 
list. 

e For Package, specify com.client. 


e Select Add the files to the archive with this prefix and specify WEB-INF/classes as 
the prefix. 
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11. 


12. 


3% Java Class Wizard x] 


Specify the project, directory and package for the new Java class. 


@ Add to open project: [ealcwaRClient | Create project... | 


© No project -- just write files to the disk. 





















Base directory: F: WorkbenchProjects\CalcWARClientisre z] Browse... | 
Package: From client 


File directory: = C:WVYorkbenchProjects\CalcVVWARClient\src\comclient 
NOTE: The entire contents of this directory will be included in the archive. 


© Add the files to the root of the archive. 


@ Add the files to the archive with this prefix: JAEB-INFiclasses 


The files will be added to this location in the archive: 
VWEB-INFiclasses/com/client 


prefix package 














sack Finish Cancel Help 


Click Finish. 


When the Java Class Wizard dialog reports that it is done creating the new Java file, click 
OK. 


The file MagicNumberBean.java is open in the Edit Pane. 


In the Edit Pane, add these import statements after the package statement: 


import javax.naming.InitialContext; 
import calc.*; 


Replace the constructor, which looks like this: 


public MagicNumberBean () 


{ 
} 


with these property variables, constructor, and getter and setter methods. The properties 
with their getter and setter methods correspond to fields in the form in magicnumber.jsp. 


/** @todo: implement this constructor */ 


private int age=0; 

private int birthday=0; 
private int bedtime=0; 

private double magicNumber=0.0; 


public MagicNumberBean() { } 
public int getAge() { return this.age; } 
public void setAge(int age) { this.age=age; } 
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public int getBirthday() { return this.birthday; } 
public void setBirthday(int day) { this.birthday=day; } 


public int getBedtime() { return this.bedtime; } 
public void setBedtime(int bedtime) { this.bedtime=bedtime; } 


public double getMagicNumber() { return this.magicNumber; } 
public void setMagicNumber (double num) { this.magicNumber=num; } 
13. Before the final closing } for the class, add the calcNumber() and getCalculatorRemote() 
methods, which have the code for calling the Web Service. 


public void calcNumber () 


{ 


double result=0; 
try 


{ 


CalculatorImplWS remote = getCalculatorRemote() ; 


result = remote.add(age, birthday) ; 
if (result != 0) 


{ 
} 


setMagicNumber (result) ; 


} 


catch (Exception _e) 


{ 


System.out.println("*** Error calculating number ***") ; 
_e.printStackTrace() ; 


} 


result = remote.multiply(result, bedtime) ; 


} 


private CalculatorImplWS getCalculatorRemote() throws Exception 


{ 


InitialContext ctx = new InitialContext(); 


String lookup = "xmlrpc:soap:calc.CalculatoriImp1lWSService"; 
CalculatorImplWSService service = 
(CalculatorImp1WSService) ctx.lookup (lookup); 
CalculatorImplWS remote = 
(CalculatorImp1WS) service.getCalculatorImp1WSPort () ; 


return remote; 


14. Save and close the file. 
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Deploying and testing the WAR 
To deploy the application, you need to specify: 


e Information in the deployment descriptor about the starting servlet or JSP page 


e Information your server needs in the format it expects 


You will do this next. 


About the deployment descriptor 


When you created the project, Workbench created an XML descriptor file appropriate to the 
type of archive you selected. For a WAR, the file is called web.xml. 


When you open web.xml for editing, the Deployment Descriptor Editor shows the XML 
elements in an expandable tree structure. You can also look at the raw XML. The editor uses the 
project’s compiled code to determine what to show, which is why you build the archive first. If 
it isn’t already built, Workbench offers to build it for you. 


EXERCISE 4-8: Build the archive 


e In Workbench, select Project>Rebuild All and Archive from the menu to create a 
deployable archive for your project. 


EXERCISE 4-9: Edit the deployment descriptor 
In this exercise you'll identify the JSP page that is the entry point for the application. 
1. In the Navigation Pane, right-click the project file CaleWARClient.spf and select Open 
Deployment Descriptor from the popup menu. 


NOTE If Workbench displays the Select Build Option dialog, select No, don’t build 
now and click OK. You can set options that cause this dialog to always or never 
display. 

Workbench opens web.xml in the Edit Pane. The editor displays the Descriptor tab, 

showing the types of information the descriptor can include. 
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Oi oe; He | 


C:WVorkbenchProjects\CalcVVAR Client VVEB-INF web.xml 


=É} Wen archive 





@ Context Parameters 
3 Servlets 

2 Servlet Mapping 
X Mime Mapping 

a Welcome Files 

xj Error Pages 


al Tag Libraries 

$ Resource References 
QÀ Security Constraints 
> Login Configuration 
I Roles 

oe Environment 

Bs EJB References 








Right-click Web Archive and select Properties from the popup menu. 
On the property sheet, specify CaleWARClient for Display Name. 
In the Edit Pane, right-click Servlets and select Add from the popup menu. 


On the property sheet, specify these values: 





Option 


Value 





Servlet name 


magicnumber 





Type 


JSP 





JSP file 








magicnumber.jsp 
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ZZ Properties Eg 


WAR Servlet | 





Servlet name: 


fragicnumber 


Type: © Servlet @ JSP 
JSP file: 


fagicnumber jsp || 
Load on startup: | 


Description: 








6. Inthe Edit Pane, right-click Servlet Mapping and select Add from the popup menu. 
7. On the property sheet, specify these values: 























Option Value 
Servlet name magicnumber 
URL pattern magicnumber 


WAR Servlet Mapping | 





Servlet name: 


fragicnumber g 


URL pattern: 


fragicnumber 


8. In the Edit Pane, right-click Welcome Files and select Add from the popup menu. 
9. On the property sheet, specify these values: 





Option Value 











Welcome File magicnumber.jsp 





10. Save and close the deployment descriptor. 
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Deploying the project 


If you’ ve done the previous lessons, most of your deployment setup has already been done. This 
exercise gives you the main steps and provides the project-specific information you’ll need to 
deploy this project. For detailed deployment instructions for all the supported servers, see 

Workbench Deployment Instructions. 


EXERCISE 4-10: Deploy the project 


1. If you haven’t created a profile for your server, select Edit>Profiles and create one now. 


(2) For information, see the server profile procedure in the deployment instructions. 


2. Use the following information to create the server-specific part of the deployment process. 


(2) For more information and exercises with detailed steps, select the section for your 
server in the deployment instructions. 





Server 


What to do 


What to specify 





SilverStream 














Create a SilverStream 
deployment plan and 
set values on the 
property sheet for the 
Web Archive item. 





Enabled — True 


Deployed object name — 
CalcWARClient 


Server Profile — Select the profile you 
defined from the dropdown list box 


Session timeout — 5 minutes, the default 
URLs — CalcWARClient, the default 
Excluded JSPs — calcnumber.jsp 
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Server 


What to do 


What to specify 





Sun Reference 
Implementation 


Create a runtime 
deployment 
descriptor called sun- 
j2ee-ri.xml with the 
content at right. Put it 
in a directory called 
META-INF and add 
the file to the project. 


<?xml version="1.0" 
encoding="Cp1252"?> 


<j2ee-ri-specific-information> 
<server-name></server-name> 
<rolemapping /> 
<web> 
<display- 
name>CalcWARClient</display- 
name> 
<context- 
root>CalcWARClient</context- 
root> 
</web> 
</j2ee-ri-specific-information> 





Jakarta Tomcat 




















BEA WebLogic | Create a WebLogic <!DOCTYPE weblogic-web-app 
descriptor called PUBLIC "-//BEA 
blogic.xml with Systems, Inc.//DTD Web 
webtogic.x Wi Application 6.0//EN" 
the content at right. "http://www.bea.com/servers/wls6 
Add it to the project 10/dtd/ 
in the WEB-INF weblogic-web-jar.dtd"> 
directory. 
<weblogic-web-app> 
<description> 
Calculator Client 
</description> 
<weblogic-version> 
</weblogic-version> 
</weblogic-web-app> 
IBM WebSphere | — — 
Oracle9i AS — — 





Specify deployment settings for your server by selecting Project>Deployment Settings 


from the menu. 


On the Server Profiles tab, select the server profile you defined above. If you have a 
secure server, specify values for User name and Password. 


On the Deployment Info tab, specify additional application-specific information, as 


follows. 
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NOTE For these tutorials, do not check Enable Rapid Deployment. For information on 
how to use rapid deployment with your server, see Archive Deployment in the 


Tools Guide. 





Server 


Option and Value 





SilverStream 


SilverStream Deployment Plan — Select the plan you 
defined in Step 2 


Overwrite existing deployment — Selected 
Verbosity — 3 


Ignore compile errors — Not selected (if JSP pages don’t 
compile successfully during deployment, don’t deploy the 
archive) 





Sun Reference 
Implementation 





Jakarta Tomcat 











BEA WebLogic WebLogic Application Name — CalculatorWARClient; used 
in the URL for accessing the Web application 

IBM WebSphere Node Name — Leave blank or specify a node you’ ve set up on 
your server 

Oracle9iAS Deployment Name — CalculatorWARClient; used in the 





URL for accessing the Web application 


Target Path — Leave blank or specify a path you’ve set up on 
your server 


Website Name — Accept the default value or specify a name 
you’ ve set up on your server 














LQ) For more details, select the section for your server in the deployment instructions. 


4. Click Deploy in the Deployment Settings dialog. 


OR 


Click OK in Deployment Settings and select Project>Deploy Archive from the menu. 


Workbench displays progress messages, errors, and warnings on the Deploy tab of the 


Output Pane. 
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TIP For most server types, full deployment will fail if your server is not running. For 
some servers you need to restart after deployment. For details, see the section for 
your server in the deployment instructions. 


EXERCISE 4-11: Test the Calculator Client application 


1. Open your browser and enter the URL for the application. It will generally include: 





Part of URL Description Typical value 





Server URL for the server, including the http://localhost/Prov 
port number (if not the default port erbsCloud/ 


80) and any server-specific data http://www.mydoma 





TIP For a SilverStream server, in.com:8080/ 
include the database to which 
you deployed the WAR 
Web application URL for the WAR CalcWARClient/ 


TIP For a SilverStream server, this is 
a relative URL that you specify 
in the deployment plan 





Page (Optional) URL for the page you (blank) 
want to view; if blank the application 
displays the welcome page specified 
in the deployment descriptor 

















For example, if the application is deployed to a local SilverStream server in a database 
called ProverbsCloud and the URL for the application is CalcWARClient, the URL would 
be: 


http: //localhost/ProverbsCloud/CalcWARClient 
You see the welcome page with a form for specifying the calculation data. 
2. Enter some values (integers only) in the form and click Submit. 


The results, displayed by calcnumber.jsp, appear below the form. 
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E] Magic Number - Microsoft Internet Explorer | [oy x] 





| File Edit View Favorites Tools Help | 





| Address ja http: //localhost/ProverbsCloud/CaleWARClient/ x] @Go Il Links ? 








| e Back ~ > - @ [2] A| QSearch GyFavoites <BHistoy | G A G QD we 








Your Magic Number 


Your magic number changes every day. 


Your age Booo | 

Day of month you were born Booo 

Hour you went to bed last night Boo t~S 
Submit | 


Drumroll... 


Your number is: 430.0 
Did you expect a winning lottery number? 





| | [F= Local intranet 


Summary of what you’ve done 


Developing the application In this lesson you built a Web application that displayed a 





form to users, used the form data when it called the Calculator Web Service, and presented the 


results of the calculation on the same JSP page. 


Using Workbench tools You used these tools in Workbench: 


e New Project Wizard (File>New Project) 

e Project Settings dialog (Project>Project Settings) 

e Web Service Wizard (File>New, Web Services tab) 
e JSP Wizard and Editor 

e Java Class Wizard and Editor 


e Deployment tools (Open Deployment Descriptor on project popup menu, Edit>Profiles, 


Project>Deployment Settings, Project>Deploy Archive) 
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Next lesson In the next lesson you will learn about additional tools for testing Web 
Services. 
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What you will learn 
This lesson teaches you how to use tools for testing your Web Service. You will learn about: 
e Viewing the WSDL in your browser 
e Inspecting message traffic with TcpTunnel 


You'll use the project for the Calculator Web Service you developed in Lesson 2, “Creating a 
Web Service”. 


What you will do 
1. View the WSDL for the deployed Web Service 


2. Edit the client code to redirect messages to TcpTunnel 


3. Run the client and observe the message traffic with TcpTunnel 


How long will it take? About 10 minutes 


NOTE You need to run your J2EE application server to query the Calculator Web Service you 
deployed in Lesson 2, “Creating a Web Service”. 


Viewing the WSDL in your browser 


As you’ ve seen, the Web Service Wizard adds several Java classes to your project. In addition, 
the wizard’s Generate WSDL file option adds a WSDL file to the project. The WSDL file 
describes your Web Service for clients that don’t have access to the actual Web Service code. In 
Source layout it’s in the src directory, and in Archive layout it’s in the WEB-INF/classes 
directory. 


If you type the URL for the Web Service in your browser, the jBroker Web code on the server 
gets a plain GET request, nota SOAP message. So instead of running a Web Service method and 
returning a SOAP message, it displays the WSDL for the Web Service. With this feature, you 
can use the Web to give other developers the information they need to develop a client 
application that calls your Web Service. 


NOTE Another way of sharing information about a deployed Web Service is in a registry, 
described in Lesson 1, “Registries and WSDL for Web Services”. 
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By 
EXERCISE 5-1: View the WSDL for the deployed Web Service 


This procedure requires a browser that understands and displays XML, such as Internet 
Explorer 5 and later. 


1. Ifthe application server where you deployed the Calculator Web Service isn’t running, 
start it now. 
2. Open your Internet Explorer browser. 


3. In Lesson 2, “Creating a Web Service” you specified an URL for the Web Service 
binding—for example, http://localhost/ProverbsCloud/Calculator/Calculator Impl. Go 
to that URL in the browser. 


The browser displays the WSDL for the Web Service. 





File Edit View Favorites Tools Help Ea 


e.>., @ a| a a. 3 
Stop Home 


Back Forward Refresh Search Favorites History 


Address ja http: //localhost/Calculator/Calculatorlmpl | @Go | Links >” 


<?xml version="1,0" encoding="UTF-8" ?> 

<definitions name="CalculatorImp|IWSService" 
targetNamespace="urn:calc.CalculatorImpl' 

“http://schemas.xmlsoap.org/wsdl/" 

="http://schemas.xmlsoap.org/wsdl/soap/" 

apenc="http://schemas.xmlsoap.org/soap/encoding/" 
“urn:cale.CalculatorImpl" 

l="http://schemas.xmlsoap.org/wsdl/" 

“http://www.w3.org/2001/XMLSchema'> 























<message name="addRequest'"> 

<part name="argO" type="xsd:double" /> 

<part name="arg1" type="xsd:double" /> 

</message> 

<message name="addResponse"> 

<part name="result" type="xsd:double" /> 

</message> 

<message name="subtractRequest"> 

«part name="argO" type="xsd:double" /> 
«part name="arg1" type="xsd:double" /> 

</message> 

emessane name="suhtractResnonse"~ 











| | | [Ei Local intranet 
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Inspecting message traffic with TcpTunnel 


One of the tools in jBroker Web is TcpTunnel, a console that displays SOAP request and 
response messages and HTTP headers sent between a client and a Web Service. The basic steps 
for using TcpTunnel are: 


1. Alter the binding URL for the Web Service in the client code to redirect requests to 
TcpTunnel using localhost and a unique port number. 


2. Start TepTunnel with arguments specifying the new port number and the original server 
name and port number. 


3. Run the client program and observe the messages on the TcpTunnel console. 


These exercises provide detailed steps for running the Calculator client with TcpTunnel. The 
steps show you how to include the altered binding URL in the test client’s code; you could also 
change the client code to accept the URL as a command-line argument. 


EXERCISE 5-2: Edit the client code to redirect messages to TcpTunnel 


In this exercise you'll change the binding URL in the client to redirect message traffic through 
TcpTunnel. 


1. Start Workbench and open the Calculator project in the CalculatorWS directory. 
TIP Ifyou opened that project recently, you can use the File>Recent Files menu item. 
2. Open CalculatorImp!WS_Stub.java in the editor. Find and highlight the binding URL 
and copy it to the clipboard. The URL is the second string in a line that looks like this: 


new com.sssw.jbroker.web.Binding("soap", 
"http: //localhost/ProverbsCloud/Calculator/CalculatorImp1") , 


3. Close the file. 

4. Open CalculatorImpIWSClient.java in the editor. 

5. Edit the getRemote() method to include code for setting the binding, then paste in the 
URL from the stub: 


public CalculatorImpl1WS getRemote(String[] args) throws Exception 


{ 


InitialContext ctx = new InitialContext () ; 


String lookup = "xmlrpc:soap:calc.CalculatoriImp1lWSService"; 
CalculatorImplWSService service = (CalculatorImplWSService) ctx.lookup (lookup); 
CalculatorImplWS remote = (CalculatorImp1WS) service.getCalculatorImp1WSPort () ; 


((javax.xml.rpc.Stub) remote). setProperty("javax.xml.rpc.service.endpoint.address", 
"http: //localhost/ProverbsCloud/Calculator/CalculatorImp1") ; 
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return remote; 


6. Inthe pasted URL, change the server and port to localhost:9090 but keep the rest of the 
Web Service's real URL. The port 9090 is an arbitrary unused port number. 


The resulting line of code looks like this: 


((javax.xml.rpc.Stub) remote) ._setProperty("javax.xml.rpc.service.endpoint.address", 
"http: //localhost:9090/ProverbsCloud/Calculator/CalculatorImp1") ; 


7. Save the file and close it. 


8. Select Project>Build to recompile CalculatorImp!WSClient. 


IS 
EXERCISE 5-3: Run the client and observe the message traffic with TcpTunnel 
In this exercise you'll start TcpTunnel and run the test client with the Client Runner window. 


1. Start TcpTunnel by opening a DOS window in the Workbench-install- 
directory\bin\win32 directory and typing a command in this format: 


tcptunnel 9090 server-with-deployed-web-service port 
For example, if the Web Service was deployed to localhost:80, type: 
tcptunnel 9090 localhost 80 
If the service was deployed to www.myweb.com, type: 
tcptunnel 9090 www.myweb.com 80 


2. In Workbench, run the test client the same way you did in Lesson 2, “Creating a Web 
Service”: select Project>Run Web Service Client Class from the menu, select the 
CalculatorImp!WSClient class, enter two numbers as arguments, and click Run. 


3. Look at the TcpTunnel console window to see the HTTP headers and SOAP messages 
being exchanged. 
The left pane contains the SOAP requests made by the client, and the right pane displays 
the responses from the Web Service. 
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Summary of what you’ve done 


Developing the application In this lesson you found out how to display WSDL for a Web 
Service published using jBroker Web and you learned how to examine the SOAP message 
traffic using TepTunnel. 


Using Workbench tools You used these tools in Workbench: 


e Edit Pane 
e  TepTunnel (Broker Web command-line tool) 


What’s next Congratulations. You’ ve finished building the Calculator Web Service and a 
client Web application for it. 


To learn more about J2EE and Workbench, try the WAR tutorial. 
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